draft-ietf-scim-api-01.txt   draft-ietf-scim-api-02.txt 
Network Working Group T. Drake, Ed. Network Working Group T. Drake, Ed.
Internet-Draft UnboundID Internet-Draft UnboundID
Intended status: Standards Track C. Mortimore Intended status: Standards Track C. Mortimore
Expires: October 17, 2013 SalesForce Expires: March 03, 2014 SalesForce
M. Ansari M. Ansari
Cisco Cisco
K. Grizzle K. Grizzle
SailPoint SailPoint
E. Wahlstroem E. Wahlstroem
Technology Nexus Technology Nexus
April 15, 2013 August 30, 2013
System for Cross-Domain Identity Management:Protocol System for Cross-Domain Identity Management:Protocol
draft-ietf-scim-api-01 draft-ietf-scim-api-02
Abstract Abstract
The System for Cross-Domain Identity Management (SCIM) specification The System for Cross-Domain Identity Management (SCIM) specification
is designed to make managing user identity in cloud based is designed to make managing user identity in cloud based
applications and services easier. The specification suite seeks to applications and services easier. The specification suite seeks to
build upon experience with existing schemas and deployments, placing build upon experience with existing schemas and deployments, placing
specific emphasis on simplicity of development and integration, while specific emphasis on simplicity of development and integration, while
applying existing authentication, authorization, and privacy models. applying existing authentication, authorization, and privacy models.
It's intent is to reduce the cost and complexity of user management It's intent is to reduce the cost and complexity of user management
operations by providing a common user schema and extension model, as operations by providing a common user schema and extension model, as
well as binding documents to provide patterns for exchanging this well as binding documents to provide patterns for exchanging this
schema using standard protocols. In essence, make it fast, cheap, schema using standard protocols. In essence, make it fast, cheap,
and easy to move users in to, out of, and around the cloud. and easy to move users in to, out of, and around the cloud.
Status of this Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 17, 2013. This Internet-Draft will expire on March 03, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
skipping to change at page 3, line 7 skipping to change at page 2, line 22
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 4 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3
1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 4 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3
1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3
2. Authentication and Authorization . . . . . . . . . . . . . . . 4 2. Authentication and Authorization . . . . . . . . . . . . . . 3
3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Creating Resources . . . . . . . . . . . . . . . . . . . . 7 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 6
3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . . 8 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 8
3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . . 8 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 8
3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8
3.2.2. List/Query Resources . . . . . . . . . . . . . . . . . 10 3.2.2. List/Query Resources . . . . . . . . . . . . . . . . 9
3.2.3. Querying Resources Using HTTP POST . . . . . . . . . . 17 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 16
3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 19 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 18
3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . . 19 3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . 18
3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . . 21 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 20
3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . . 29 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 27
3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 45 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 42
3.7. Additional retrieval query parameters . . . . . . . . . . 45 3.7. Additional retrieval query parameters . . . . . . . . . . 42
3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . . 46 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 43
3.9. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 46 3.9. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 43
3.10. API Versioning . . . . . . . . . . . . . . . . . . . . . . 48 3.10. API Versioning . . . . . . . . . . . . . . . . . . . . . 45
3.11. Versioning Resources . . . . . . . . . . . . . . . . . . . 48 3.11. Versioning Resources . . . . . . . . . . . . . . . . . . 45
3.12. HTTP Method Overloading . . . . . . . . . . . . . . . . . 50 3.12. HTTP Method Overloading . . . . . . . . . . . . . . . . . 47
4. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 50 4. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 48
4.1. Associating Consumers to Tenants . . . . . . . . . . . . . 51 4.1. Associating Consumers to Tenants . . . . . . . . . . . . 49
4.1.1. URL Prefix Example . . . . . . . . . . . . . . . . . . 51 4.1.1. URL Prefix Example . . . . . . . . . . . . . . . . . 49
4.1.2. Subdomain Example . . . . . . . . . . . . . . . . . . 52 4.1.2. Subdomain Example . . . . . . . . . . . . . . . . . . 49
4.1.3. HTTP Header . . . . . . . . . . . . . . . . . . . . . 52 4.1.3. HTTP Header . . . . . . . . . . . . . . . . . . . . . 49
4.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . . 52 4.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 49
5. Security Considerations . . . . . . . . . . . . . . . . . . . 52 5. Security Considerations . . . . . . . . . . . . . . . . . . . 50
6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 52 6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 50
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 50
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 53 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 50
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50
1. Introduction and Overview 1. Introduction and Overview
The SCIM Protocol is an application-level, REST protocol for The SCIM Protocol is an application-level, REST protocol for
provisioning and managing identity data on the web. The protocol provisioning and managing identity data on the web. The protocol
supports creation, modification, retrieval, and discovery of core supports creation, modification, retrieval, and discovery of core
identity Resources; i.e., Users and Groups, as well as custom identity Resources; i.e., Users and Groups, as well as custom
Resource extensions. Resource extensions.
1.1. Intended Audience 1.1. Intended Audience
skipping to change at page 4, line 30 skipping to change at page 3, line 34
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. These document are to be interpreted as described in [RFC2119]. These
keywords are capitalized when used to unambiguously specify keywords are capitalized when used to unambiguously specify
requirements of the protocol or application features and behavior requirements of the protocol or application features and behavior
that affect the interoperability and security of implementations. that affect the interoperability and security of implementations.
When these words are not capitalized, they are meant in their When these words are not capitalized, they are meant in their
natural-language sense. natural-language sense.
For purposes of readability examples are not URL encoded. For purposes of readability examples are not URL encoded.
Implementers MUST percent encode URLs as described in RFC3896 2.1. Implementers MUST percent encode URLs as described in RFC3896 2.1
[1].
1.3. Definitions 1.3. Definitions
Base URL: The SCIM REST API is always relative to a Base URL. The Base URL: The SCIM REST API is always relative to a Base URL. The
Base URL MUST NOT contain a query string as Consumers may append Base URL MUST NOT contain a query string as Consumers may append
additional path information and query parameters as part of additional path information and query parameters as part of
forming the request. Example: https://example.com/scim/v1/ forming the request. Example: https://example.com/scim/v1/
2. Authentication and Authorization 2. Authentication and Authorization
The SCIM protocol does not define a scheme for authentication and The SCIM protocol does not define a scheme for authentication and
authorization therefore implementers are free to choose mechanisms authorization therefore implementers are free to choose mechanisms
appropriate to their use cases. The choice of authentication appropriate to their use cases. The choice of authentication
mechanism will impact interoperability. It is RECOMMENDED that mechanism will impact interoperability. It is RECOMMENDED that
clients be implemented in such a way that new authentication schemes clients be implemented in such a way that new authentication schemes
can be deployed. Implementers SHOULD support existing can be deployed. Implementers SHOULD support existing authentication
authentication/authorization schemes. In particular, OAuth2 Bearer /authorization schemes. In particular, OAuth2 Bearer Token [2] is
Token [1] is RECOMMENDED. Appropriate security considerations of the RECOMMENDED. Appropriate security considerations of the selected
selected authentication and authorization schemes SHOULD be taken. authentication and authorization schemes SHOULD be taken. Because
Because this protocol uses HTTP response status codes as the primary this protocol uses HTTP response status codes as the primary means of
means of reporting the result of a request, servers are advised to reporting the result of a request, servers are advised to respond to
respond to unauthorized or unauthenticated requests using the 401 unauthorized or unauthenticated requests using the 401 response code
response code in accordance with section 10.4.2 of RFC2616. in accordance with section 10.4.2 of RFC2616 [3].
All examples assume OAuth2 bearer token; e.g., All examples assume OAuth2 bearer token; e.g.,
GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1
Host: example.com Host: example.com
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
The context of the request (i.e. the user for whom data is being The context of the request (i.e. the user for whom data is being
requested) MUST be inferred by Service Providers. requested) MUST be inferred by Service Providers.
3. API 3. API
The SCIM protocol specifies well known endpoints and HTTP methods for The SCIM protocol specifies well known endpoints and HTTP methods for
managing Resources defined in the core schema; i.e., User and Group managing Resources defined in the core schema; i.e., User and Group
Resources correspond to /Users and /Groups respectively. Service Resources correspond to /Users and /Groups respectively. Service
Providers that support extended Resources SHOULD define Resource Providers that support extended Resources SHOULD define Resource
endpoints using the established convention; pluralize the Resource endpoints using the established convention; pluralize the Resource
name defined in the extended schema by appending an 's'. Given there name defined in the extended schema by appending an 's'. Given there
are cases where Resource pluralization is ambiguous; e.g., a Resource are cases where Resource pluralization is ambiguous; e.g., a Resource
named 'person' is legitimately 'persons' and 'people' Consumers named 'person' is legitimately 'persons' and 'people' Consumers
SHOULD discover Resource endpoints via the Schema Sub-Attribute SHOULD discover Resource endpoints via the Resource Type attribute
'endpoint'. 'endpoint'.
GET Retrieves a complete or partial Resource. GET Retrieves a complete or partial Resource.
POST Create new Resource, perform an extended Search, or bulk modify POST Create new Resource, perform an extended Search, or bulk modify
Resources. Resources.
PUT Modifies a Resource with a complete, Consumer specified Resource PUT Modifies a Resource with a complete, Consumer specified Resource
(replace). (replace).
PATCH Modifies a Resource with a set of Consumer specified changes PATCH Modifies a Resource with a set of Consumer specified changes
(partial update). (partial update).
DELETE Deletes a Resource. DELETE Deletes a Resource.
+------------+--------------------+---------------+-----------------+ +-------------+---------------------+-----------+-------------------+
| Resource | Endpoint | Operations | Description | | Resource | Endpoint | Operation | Description |
+------------+--------------------+---------------+-----------------+ | | | s | |
| User | /Users | GET | Retrieve/Add/Mo | +-------------+---------------------+-----------+-------------------+
| | | (Section 3.2. | dify Users | | User | /Users | GET | Retrieve/Add/Modi |
| | | 1), POST | | | | | (Section | fy Users |
| | | (Section 3.1 | | | | | 3.2.1), | |
| | | ),PUT | | | | | POST | |
| | | (Section 3. | | | | | (Section | |
| | | 3.1), PATCH | | | | | 3.1), PUT | |
| | | (Section 3 | | | | | (Section | |
| | | .3.2), DELETE | | | | | 3.3.1), | |
| | | (Section | | | | | PATCH | |
| | | 3.4) | | | | | (Section | |
| Group | /Groups | GET | Retrieve/Add/Mo | | | | 3.3.2), | |
| | | (Section 3.2. | dify Groups | | | | DELETE | |
| | | 1), POST | | | | | (Section | |
| | | (Section 3.1 | | | | | 3.4) | |
| | | ),PUT | | | Group | /Groups | GET | Retrieve/Add/Modi |
| | | (Section 3. | | | | | (Section | fy Groups |
| | | 3.1), PATCH | | | | | 3.2.1), | |
| | | (Section 3 | | | | | POST | |
| | | .3.2), DELETE | | | | | (Section | |
| | | (Section | | | | | 3.1), PUT | |
| | | 3.4) | | | | | (Section | |
| Service | /ServiceProviderCo | GET | Retrieve the | | | | 3.3.1), | |
| Provider | nfigs | (Section 3.2. | Service | | | | PATCH | |
| Configurat | | 1) | Provider's | | | | (Section | |
| ion | | | Configuration | | | | 3.3.2), | |
| Schema | /Schemas | GET | Retrieve a | | | | DELETE | |
| | | (Section 3.2. | Resource's | | | | (Section | |
| | | 1) | Schema | | | | 3.4) | |
| Bulk | /Bulk | POST | Bulk modify | | Service | /ServiceProviderCon | GET | Retrieve the |
| | | (Section 3.5) | Resources | | Provider Co | figs | (Section | Service |
| Search | [prefix]/.search | POST | Perform a | | nfiguration | | 3.2.1) | Provider's |
| | | (Section 3.2. | search at | | | | | Configuration |
| | | 3) | system root or | | Resource | /ResourceTypes | GET | Retrieve the |
| | | | within a | | Type | | (Section | supported |
| | | | resource | | | | 3.2.1) | Resource Types |
| | | | endpoint for | | Schema | /Schemas | GET | Retrieve a |
| | | | one or more | | | | (Section | Resource's Schema |
| | | | resource types | | | | 3.2.1) | |
| | | | using POST. | | Bulk | /Bulk | POST | Bulk modify |
+------------+--------------------+---------------+-----------------+ | | | (Section | Resources |
| | | 3.5) | |
| Search | [prefix]/.search | POST | Perform a search |
| | | (Section | at system root or |
| | | 3.2.3) | within a resource |
| | | | endpoint for one |
| | | | or more resource |
| | | | types using POST. |
+-------------+---------------------+-----------+-------------------+
Table 1: Defined endpoints Table 1: Defined endpoints
All requests to the Service Provider are made via HTTP operations on All requests to the Service Provider are made via HTTP operations [4]
a URL derived from the Base URL. Responses are returned in the body on a URL derived from the Base URL. Responses are returned in the
of the HTTP response, formatted as JSON. Response and error codes body of the HTTP response, formatted as JSON. Response and error
SHOULD be transmitted via the HTTP status code of the response (if codes SHOULD be transmitted via the HTTP status code of the response
possible), and SHOULD also be specified in the body of the response. (if possible), and SHOULD also be specified in the body of the
response.
3.1. Creating Resources 3.1. Creating Resources
To create new Resources, clients send POST requests to the Resource To create new Resources, clients send POST requests to the Resource
endpoint; i.e., /Users or /Groups. endpoint; i.e., /Users or /Groups.
Successful Resource creation is indicated with a 201 ("Created") Successful Resource creation is indicated with a 201 ("Created")
response code. Upon successful creation, the response body MUST response code. Upon successful creation, the response body MUST
contain the newly created Resource. Since the server is free to contain the newly created Resource. Since the server is free to
alter and/or ignore POSTed content, returning the full representation alter and/or ignore POSTed content, returning the full representation
skipping to change at page 7, line 29 skipping to change at page 7, line 4
server views of the new Resource. When a Resource is created, its server views of the new Resource. When a Resource is created, its
URI must be returned in the response Location header. URI must be returned in the response Location header.
If the Service Provider determines creation of the requested Resource If the Service Provider determines creation of the requested Resource
conflicts with existing resources; e.g., a User Resource with a conflicts with existing resources; e.g., a User Resource with a
duplicate userName, the Service Provider MUST return a 409 error and duplicate userName, the Service Provider MUST return a 409 error and
SHOULD indicate the conflicting attribute(s) in the body of the SHOULD indicate the conflicting attribute(s) in the body of the
response. response.
Below, the client sends a POST request containing a User Below, the client sends a POST request containing a User
POST /Users HTTP/1.1 POST /Users HTTP/1.1
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
{ {
"schemas":["urn:scim:schemas:core:1.0"], "schemas":["urn:scim:schemas:core:2.0:User"],
"userName":"bjensen", "userName":"bjensen",
"externalId":"bjensen", "externalId":"bjensen",
"name":{ "name":{
"formatted":"Ms. Barbara J Jensen III", "formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen", "familyName":"Jensen",
"givenName":"Barbara" "givenName":"Barbara"
} }
} }
The server signals a successful creation with a status code of 201. The server signals a successful creation with a status code of 201.
The response includes a Location header indicating the User URI, and The response includes a Location header indicating the User URI, and
a representation of that User in the body of the response. a representation of that User in the body of the response.
HTTP/1.1 201 Created HTTP/1.1 201 Created
Content-Type: application/json Content-Type: application/json
Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646 Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1" ETag: W/"e180ee84f0671b1"
{ {
"schemas":["urn:scim:schemas:core:1.0"], "schemas":["urn:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646", "id":"2819c223-7f76-453a-919d-413861904646",
"externalId":"bjensen", "externalId":"bjensen",
"meta":{ "meta":{
"resourceType":"User", "resourceType":"User",
"created":"2011-08-01T21:32:44.882Z", "created":"2011-08-01T21:32:44.882Z",
"lastModified":"2011-08-01T21:32:44.882Z", "lastModified":"2011-08-01T21:32:44.882Z",
"location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"e180ee84f0671b1\"" "version":"W\/\"e180ee84f0671b1\""
}, },
"name":{ "name":{
"formatted":"Ms. Barbara J Jensen III", "formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen", "familyName":"Jensen",
"givenName":"Barbara" "givenName":"Barbara"
}, },
"userName":"bjensen" "userName":"bjensen"
} }
3.1.1. Resource Types 3.1.1. Resource Types
When adding a resource to a specific endpoint, the meta attribute When adding a resource to a specific endpoint, the meta attribute
"resourceType" SHALL be set by the Service Provider to the "resourceType" SHALL be set by the Service Provider to the
corresponding resource type for the endpoint and any extension types. corresponding Resource Type for the endpoint. For example, "/Users"
For example, "/Users" will set "resourceType" to "User", and will set "resourceType" to "User", and "/Groups" will set
"/Groups" will set "resourceType" to "Group". "resourceType" to "Group".
[TBD: For extended resource types, the "resourceType" attribute SHALL
be set by the Service Provider to have multiple values including the
base type plus any extneded types (e.g. 'User' and 'Employee').]
3.2. Retrieving Resources 3.2. Retrieving Resources
Users and Group Resources are retrieved via opaque, unique URLs or Users and Group Resources are retrieved via opaque, unique URLs or
via Query. Service Providers MAY choose to respond with a sub-set of via Query. Service Providers MAY choose to respond with a sub-set of
Resource attributes, though MUST minimally return the Resource id and Resource attributes, though MUST minimally return the Resource id and
meta attributes. meta attributes.
3.2.1. Retrieving a known Resource 3.2.1. Retrieving a known Resource
skipping to change at page 10, line 5 skipping to change at page 8, line 37
The below example retrieves a single User via the /Users endpoint. The below example retrieves a single User via the /Users endpoint.
GET /Users/2819c223-7f76-453a-919d-413861904646 GET /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
The server responds with: The server responds with:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646 Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"f250dd84f0671c3" ETag: W/"f250dd84f0671c3"
{ {
"schemas":["urn:scim:schemas:core:1.0"], "schemas":["urn:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646, "id":"2819c223-7f76-453a-919d-413861904646,
"externalId":"bjensen", "externalId":"bjensen",
"meta":{ "meta":{
"resourceType":"User", "resourceType":"User",
"created":"2011-08-01T18:29:49.793Z", "created":"2011-08-01T18:29:49.793Z",
"lastModified":"2011-08-01T18:29:49.793Z", "lastModified":"2011-08-01T18:29:49.793Z",
"location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"f250dd84f0671c3\"" "version":"W\/\"f250dd84f0671c3\""
}, },
"name":{ "name":{
"formatted":"Ms. Barbara J Jensen III", "formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen", "familyName":"Jensen",
"givenName":"Barbara" "givenName":"Barbara"
}, },
"userName":"bjensen", "userName":"bjensen",
"phoneNumbers":[ "phoneNumbers":[
{ {
"value":"555-555-8377", "value":"555-555-8377",
"type":"work" "type":"work"
} }
], ],
"emails":[ "emails":[
{ {
"value":"bjensen@example.com", "value":"bjensen@example.com",
"type":"work" "type":"work"
} }
] ]
} }
3.2.2. List/Query Resources 3.2.2. List/Query Resources
SCIM defines a standard set of operations that can be used to filter, SCIM defines a standard set of operations that can be used to filter,
sort, and paginate response results. The operations are specified by sort, and paginate response results. The operations are specified by
adding query parameters to the Resource's endpoint. Service adding query parameters to the Resource's endpoint. Service
Providers MAY support additional query parameters not specified here, Providers MAY support additional query parameters not specified here,
and Providers SHOULD ignore any query parameters they don't and Providers SHOULD ignore any query parameters they don't
recognize. recognize.
List and query responses MUST be identified using the following URI:
'urn:scim:schemas:core:2.0:ListResponse'. The following attributes
are defined for list and query responses:
totalResults The total number of results returned by the list or
query operation. This may not be equal to the number of elements
in the Resources attribute of the list response if pagination
(Section 3.2.2.4) is requested. REQUIRED.
Resources A multi-valued list of complex objects containing the
requested resources. This may be a subset of the full set of
Resources if pagination (Section 3.2.2.4) is requested. REQUIRED.
startIndex The 1-based index of the first result in the current set
of list results. REQUIRED if pagination (Section 3.2.2.4) is
requested.
itemsPerPage The number of Resources returned in a list response
page. REQUIRED if pagination (Section 3.2.2.4) is requested.
The below example returns the userName for all Users: The below example returns the userName for all Users:
GET /Users?attributes=userName GET /Users?attributes=userName
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
{ {
"schemas":["urn:scim:schemas:core:2.0:ListResponse"],
"totalResults":2, "totalResults":2,
"schemas":["urn:scim:schemas:core:1.0"],
"Resources":[ "Resources":[
{ {
"userName":"bjensen" "userName":"bjensen"
}, },
{ {
"userName":"jsmith" "userName":"jsmith"
} }
] ]
} }
skipping to change at page 11, line 38 skipping to change at page 10, line 47
Queries MAY be performed against a SCIM: Queries MAY be performed against a SCIM:
Resource (e.g. /Users/{userid}), Resource (e.g. /Users/{userid}),
Resource Type endpoint (e.g. /Users or /Groups), or Resource Type endpoint (e.g. /Users or /Groups), or
Server Root (e.g. /). Server Root (e.g. /).
A search against a server root indicates that ALL resources within A search against a server root indicates that ALL resources within
the server SHALL be included subject to filtering. For example, a the server SHALL be included subject to filtering. For example, a
filter against 'resourceType' could be used to restrict results to filter against 'meta.resourceType' could be used to restrict results
one or more specific resource types. to one or more specific resource types.
When processing search operations across endpoints that include more When processing search operations across endpoints that include more
than one SCIM resource type (e.g. a search from the server root than one SCIM resource type (e.g. a search from the server root
endpoint), filters MUST be processed in the same fashion as outlined endpoint), filters MUST be processed in the same fashion as outlined
in Section 3.2.2.2. For filtered attributes that are not part of a in Section 3.2.2.2. For filtered attributes that are not part of a
particular resource type, the service provider SHALL treat the particular resource type, the service provider SHALL treat the
attribute as if there is no attribute value. For example, a presence attribute as if there is no attribute value. For example, a presence
or equality filter for an undefined attribute evaluates as FALSE. or equality filter for an undefined attribute evaluates as FALSE.
3.2.2.2. Filtering 3.2.2.2. Filtering
Filtering is OPTIONAL. Consumers may request a subset of Resources Filtering is OPTIONAL. Consumers may request a subset of Resources
by specifying the 'filter' URL query parameter containing a filter by specifying the 'filter' URL query parameter containing a filter
expression. When specified only those Resources matching the filter expression. When specified only those Resources matching the filter
expression SHALL be returned. The expression language that is used expression SHALL be returned. The expression language that is used
in the filter parameter supports references to attributes and in the filter parameter supports references to attributes and
literals. The literal values can be strings enclosed in double literals. The literal values can be strings enclosed in double
quotes, numbers, date times enclosed in double quotes, and Boolean quotes, numbers, date times enclosed in double quotes, and Boolean
values; i.e., true or false. String literals MUST be valid JSON values; i.e., true or false. String literals MUST be valid JSON
strings [2]. strings [5].
The attribute name and attribute operator are case insensitive. For The attribute name and attribute operator are case insensitive. For
example, the following two expressions will evaluate to the same example, the following two expressions will evaluate to the same
logical value: logical value:
filter=userName Eq "john" filter=userName Eq "john"
filter=Username eq "john" filter=Username eq "john"
The filter parameter MUST contain at least one valid Boolean The filter parameter MUST contain at least one valid Boolean
expression. Each expression MUST contain an attribute name followed expression. Each expression MUST contain an attribute name followed
by an attribute operator and optional value. Multiple expressions by an attribute operator and optional value. Multiple expressions
MAY be combined using the two logical operators. Furthermore MAY be combined using the two logical operators. Furthermore
expressions can be grouped together using "()". expressions can be grouped together using "()".
The operators supported in the expression are listed in the following The operators supported in the expression are listed in the following
table. table.
+----------+-------------+------------------------------------------+ +-----------+---------------+---------------------------------------+
| Operator | Description | Behavior | | Operator | Description | Behavior |
+----------+-------------+------------------------------------------+ +-----------+---------------+---------------------------------------+
| eq | equal | The attribute and operator values must | | eq | equal | The attribute and operator values |
| | | be identical for a match. | | | | must be identical for a match. |
| co | contains | The entire operator value must be a | | co | contains | The entire operator value must be a |
| | | substring of the attribute value for a | | | | substring of the attribute value for |
| | | match. | | | | a match. |
| sw | starts with | The entire operator value must be a | | sw | starts with | The entire operator value must be a |
| | | substring of the attribute value, | | | | substring of the attribute value, |
| | | starting at the beginning of the | | | | starting at the beginning of the |
| | | attribute value. This criterion is | | | | attribute value. This criterion is |
| | | satisfied if the two strings are | | | | satisfied if the two strings are |
| | | identical. | | | | identical. |
| pr | present | If the attribute has a non-empty value, | | pr | present (has | If the attribute has a non-empty |
| | (has value) | or if it contains a non-empty node for | | | value) | value, or if it contains a non-empty |
| | | complex attributes there is a match. | | | | node for complex attributes there is |
| gt | greater | If the attribute value is greater than | | | | a match. |
| | than | operator value, there is a match. The | | gt | greater than | If the attribute value is greater |
| | | actual comparison is dependent on the | | | | than operator value, there is a |
| | | attribute type. For string attribute | | | | match. The actual comparison is |
| | | types, this is a lexicographical | | | | dependent on the attribute type. For |
| | | comparison and for DateTime types, it is | | | | string attribute types, this is a |
| | | a chronological comparison. | | | | lexicographical comparison and for |
| ge | greater | If the attribute value is greater than | | | | DateTime types, it is a chronological |
| | than or | or equal to the operator value, there is | | | | comparison. |
| | equal | a match. The actual comparison is | | ge | greater than | If the attribute value is greater |
| | | dependent on the attribute type. For | | | or equal | than or equal to the operator value, |
| | | string attribute types, this is a | | | | there is a match. The actual |
| | | lexicographical comparison and for | | | | comparison is dependent on the |
| | | DateTime types, it is a chronological | | | | attribute type. For string attribute |
| | | comparison. | | | | types, this is a lexicographical |
| lt | less than | If the attribute value is less than | | | | comparison and for DateTime types, it |
| | | operator value, there is a match. The | | | | is a chronological comparison. |
| | | actual comparison is dependent on the | | lt | less than | If the attribute value is less than |
| | | attribute type. For string attribute | | | | operator value, there is a match. The |
| | | types, this is a lexicographical | | | | actual comparison is dependent on the |
| | | comparison and for DateTime types, it is | | | | attribute type. For string attribute |
| | | a chronological comparison. | | | | types, this is a lexicographical |
| le | less than | If the attribute value is less than or | | | | comparison and for DateTime types, it |
| | or equal | equal to the operator value, there is a | | | | is a chronological comparison. |
| | | match. The actual comparison is | | le | less than or | If the attribute value is less than |
| | | dependent on the attribute type. For | | | equal | or equal to the operator value, there |
| | | string attribute types, this is a | | | | is a match. The actual comparison is |
| | | lexicographical comparison and for | | | | dependent on the attribute type. For |
| | | DateTime types, it is a chronological | | | | string attribute types, this is a |
| | | comparison. | | | | lexicographical comparison and for |
+----------+-------------+------------------------------------------+ | | | DateTime types, it is a chronological |
| | | comparison. |
+-----------+---------------+---------------------------------------+
Table 2: Attribute Operators Table 2: Attribute Operators
+----------+-------------+------------------------------------------+ +-------------+-----------------+-----------------------------------+
| Operator | Description | Behavior | | Operator | Description | Behavior |
+----------+-------------+------------------------------------------+ +-------------+-----------------+-----------------------------------+
| and | Logical And | The filter is only a match if both | | and | Logical And | The filter is only a match if |
| | | expressions evaluate to true. | | | | both expressions evaluate to |
| or | Logical or | The filter is a match if either | | | | true. |
| | | expression evaluates to true. | | or | Logical or | The filter is a match if either |
+----------+-------------+------------------------------------------+ | | | expression evaluates to true. |
+-------------+-----------------+-----------------------------------+
Table 3: Logical Operators Table 3: Logical Operators
+----------+-------------+------------------------------------------+ +-------------+---------------+-------------------------------------+
| Operator | Description | Behavior | | Operator | Description | Behavior |
+----------+-------------+------------------------------------------+ +-------------+---------------+-------------------------------------+
| () | Precedence | Boolean expressions may be grouped using | | () | Precedence | Boolean expressions may be grouped |
| | grouping | parentheses to change the standard order | | | grouping | using parentheses to change the |
| | | of operations; i.e., evaluate OR logical | | | | standard order of operations; i.e., |
| | | operators before logical AND operators. | | | | evaluate OR logical operators |
+----------+-------------+------------------------------------------+ | | | before logical AND operators. |
+-------------+---------------+-------------------------------------+
Table 4: Grouping Operators Table 4: Grouping Operators
Filters MUST be evaluated using standard order of operations. Filters MUST be evaluated using standard order of operations [6].
Attribute operators have the highest precedence, followed by the Attribute operators have the highest precedence, followed by the
grouping operator (i.e, parentheses), followed by the logical AND grouping operator (i.e, parentheses), followed by the logical AND
operator, followed by the logical OR operator. operator, followed by the logical OR operator.
If the specified attribute in a filter expression is a multi-valued If the specified attribute in a filter expression is a multi-valued
attribute, the Resource MUST match if any of the instances of the attribute, the Resource MUST match if any of the instances of the
given attribute match the specified criterion; e.g. if a User has given attribute match the specified criterion; e.g. if a User has
multiple emails values, only one has to match for the entire User to multiple emails values, only one has to match for the entire User to
match. For complex attributes, a fully qualified Sub-Attribute MUST match. For complex attributes, a fully qualified Sub-Attribute MUST
be specified using standard attribute notation (Section 3.8). For be specified using standard attribute notation (Section 3.8). For
skipping to change at page 16, line 19 skipping to change at page 15, line 20
3.2.2.4. Pagination 3.2.2.4. Pagination
Pagination parameters can be used together to "page through" large Pagination parameters can be used together to "page through" large
numbers of Resources so as not to overwhelm the Consumer or Service numbers of Resources so as not to overwhelm the Consumer or Service
Provider. Pagination is not session based hence Consumers SHOULD Provider. Pagination is not session based hence Consumers SHOULD
never assume repeatable results. For example, a request for a list never assume repeatable results. For example, a request for a list
of 10 Resources beginning with a startIndex of 1 may return different of 10 Resources beginning with a startIndex of 1 may return different
results when repeated as a Resource in the original result could be results when repeated as a Resource in the original result could be
deleted or new ones could be added in-between requests. Pagination deleted or new ones could be added in-between requests. Pagination
parameters and general behavior are derived from the OpenSearch parameters and general behavior are derived from the OpenSearch
Protocol [3]. Protocol [7].
The following table describes the URL pagination parameters. The following table describes the URL pagination parameters.
+------------+-------------------+----------------------------------+ +-------------+----------------------+------------------------------+
| Parameter | Description | Default | | Parameter | Description | Default |
+------------+-------------------+----------------------------------+ +-------------+----------------------+------------------------------+
| startIndex | The 1-based index | 1 | | startIndex | The 1-based index of | 1 |
| | of the first | | | | the first search | |
| | search result. | | | | result. | |
| count | Non-negative | None. When specified the | | count | Non-negative | None. When specified the |
| | Integer. | Service Provider MUST not return | | | Integer. Specifies | Service Provider MUST not |
| | Specifies the | more results than specified | | | the desired maximum | return more results than |
| | desired maximum | though MAY return fewer results. | | | number of search | specified though MAY return |
| | number of search | If unspecified, the maximum | | | results per page; | fewer results. If |
| | results per page; | number of results is set by the | | | e.g., 10. | unspecified, the maximum |
| | e.g., 10. | Service Provider. | | | | number of results is set by |
+------------+-------------------+----------------------------------+ | | | the Service Provider. |
+-------------+----------------------+------------------------------+
Table 5: Pagination Request parameters Table 5: Pagination Request parameters
The following table describes the query response pagination The following table describes the query response pagination
attributes specified by the Service Provider. attributes specified by the Service Provider.
+--------------+----------------------------------------------------+ +------------------+------------------------------------------------+
| Element | Description | | Element | Description |
+--------------+----------------------------------------------------+ +------------------+------------------------------------------------+
| itemsPerPage | Non-negative Integer. Specifies the number of | | itemsPerPage | Non-negative Integer. Specifies the number of |
| | search results returned in a query response page; | | | search results returned in a query response |
| | e.g., 10. | | | page; e.g., 10. |
| totalResults | Non-negative Integer. Specifies the total number | | totalResults | Non-negative Integer. Specifies the total |
| | of results matching the Consumer query; e.g., | | | number of results matching the Consumer query; |
| | 1000. | | | e.g., 1000. |
| startIndex | The 1-based index of the first result in the | | startIndex | The 1-based index of the first result in the |
| | current set of search results; e.g., 1. | | | current set of search results; e.g., 1. |
+--------------+----------------------------------------------------+ +------------------+------------------------------------------------+
Table 6: Pagination Response Elements Table 6: Pagination Response Elements
For example, to retrieve the first 10 Users set the startIndex to 1 For example, to retrieve the first 10 Users set the startIndex to 1
and the count to 10. and the count to 10.
GET /Users?startIndex=1&count=10 GET /Users?startIndex=1&count=10
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
{ {
"totalResults":100, "totalResults":100,
"itemsPerPage":10, "itemsPerPage":10,
"startIndex":1, "startIndex":1,
"schemas":["urn:scim:schemas:core:1.0"], "schemas":["urn:scim:schemas:core:2.0"],
"Resources":[{ "Resources":[{
... ...
}] }]
} }
Given the example above, to continue paging set the startIndex to 11 Given the example above, to continue paging set the startIndex to 11
and re-fetch; i.e., /Users?startIndex=11&count=10 and re-fetch; i.e., /Users?startIndex=11&count=10
3.2.3. Querying Resources Using HTTP POST 3.2.3. Querying Resources Using HTTP POST
skipping to change at page 17, line 44 skipping to change at page 16, line 46
using the HTTP POST verb combined with the '/.search' path extension. using the HTTP POST verb combined with the '/.search' path extension.
The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL
be used to indicate the HTTP POST verb is intended to be a query be used to indicate the HTTP POST verb is intended to be a query
operation. operation.
To create a new search result set, a SCIM client sends an HTTP POST To create a new search result set, a SCIM client sends an HTTP POST
request to the desired SCIM resource endpoint (ending in '/.search'). request to the desired SCIM resource endpoint (ending in '/.search').
The body of the POST request MAY include any of the parameters as The body of the POST request MAY include any of the parameters as
defined in Section 3.2.2. defined in Section 3.2.2.
Search requests MUST be identified using the following URI:
'urn:scim:schemas:core:2.0:SearchRequest'. The following attributes
are defined for search requests:
attributes A multi-valued list of strings indicating the names of
Resource attributes to return in the response. Attribute names
MUST be in standard attribute notation (Section 3.8) form. See
additional retrieval query parameters (Section 3.7). OPTIONAL.
filter The filter string used to request a subset of Resources. The
filter string MUST be a valid filter (Section 3.2.2.2) expression.
OPTIONAL.
sortBy A string indicating the attribute whose value SHALL be used
to order the returned responses. The sortBy attribute MUST be in
standard attribute notation (Section 3.8) form. See sorting
(Section 3.2.2.3). OPTIONAL.
sortOrder A string indicating the order in which the sortBy
parameter is applied. Allowed values are "ascending" and
"descending". See sorting (Section 3.2.2.3). OPTIONAL.
startIndex An integer indicating the 1-based index of the first
search result. See pagination (Section 3.2.2.4). OPTIONAL.
count An integer indicating the desired maximum number of search
results per page. See pagination (Section 3.2.2.4). OPTIONAL.
After receiving a HTTP POST request, a response is returned as After receiving a HTTP POST request, a response is returned as
specified in Section 3.2.2. specified in Section 3.2.2.
[NOTE: See resourceType meta attribute in example below --> need to
update rest of document!]
The following example shows an HTTP POST Search request with search The following example shows an HTTP POST Search request with search
parameters attributes, filter, and count included: parameters attributes, filter, and count included:
POST /.search
Host: example.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{ POST /.search
"schemas": ["urn:scim:schemas:core:1.0"], Host: example.com
"attributes":["displayName","username"], Accept: application/json
"filter":"displayName sw \"smith\"", Content-Type: application/json
"count":10 Authorization: Bearer h480djs93hd8
} Content-Length: ...
{
"schemas": ["urn:scim:schemas:core:2.0:SearchRequest"],
"attributes": ["displayName", "username"],
"filter": "displayName sw \"smith\"",
"startIndex": 1,
"count": 10
}
Figure 1: Example POST Search Request Figure 1: Example POST Search Request
A search response is shown with the first page of results. For A search response is shown with the first page of results. For
brevity reasons, only two matches are shown: one User and one Group. brevity reasons, only two matches are shown: one User and one Group.
HTTP/1.1 200 OK
Content-Type: application/json HTTP/1.1 200 OK
Location: https://example.com/.search Content-Type: application/json
{ Location: https://example.com/.search
"totalResults":100, {
"itemsPerPage":10, "schemas": ["urn:scim:schemas:core:2.0:ListResponse"],
"startIndex":1, "totalResults":100,
"schemas":["urn:scim:schemas:core:1.0"], "itemsPerPage":10,
"Resources":[ "startIndex":1,
{ "Resources":[
"meta":{ {
"location": "meta":{
"https://example.com/Users/2819c223-7f76-413861904646", "location":
"resourceType":"User", "https://example.com/Users/2819c223-7f76-413861904646",
"lastModified": ... "resourceType":"User",
} "lastModified": ...
"username":"jsmith", }
"displayName":"Smith, James" "username":"jsmith",
}, "displayName":"Smith, James"
{ },
"meta":{ {
"location": "meta":{
"https://example.com/Groups/c8596b90-7539-4f20968d1908", "location":
"resourceType":"Group", "https://example.com/Groups/c8596b90-7539-4f20968d1908",
"lastModified": ... "resourceType":"Group",
} "lastModified": ...
"displayName":"Smith Family" }
}, "displayName":"Smith Family"
... },
] ...
} ]
}
Figure 2: Example POST Search Response Figure 2: Example POST Search Response
3.3. Modifying Resources 3.3. Modifying Resources
Resources can be modified in whole or in part via PUT or PATCH, Resources can be modified in whole or in part via PUT or PATCH,
respectively. Implementers MUST support PUT as specified in RFC2616 respectively. Implementers MUST support PUT as specified in RFC2616
. Resources such as Groups may be very large hence implementers [8] . Resources such as Groups may be very large hence implementers
SHOULD support PATCH [4] to enable partial resource modifications. SHOULD support PATCH [9] to enable partial resource modifications.
3.3.1. Modifying with PUT 3.3.1. Modifying with PUT
PUT performs a full update. Consumers must retrieve the entire PUT performs a full update. Consumers must retrieve the entire
Resource and PUT the desired modifications as the operation Resource and PUT the desired modifications as the operation
overwrites all previously stored data with the exception of the overwrites all previously stored data with the exception of the
password attribute. If the password attribute of the User resource password attribute. If the password attribute of the User resource
is unspecified, it should be left in-tact. Since this performs a is unspecified, it should be left in-tact. Since this performs a
full update, Consumers MAY send read-only attributes of the retrieved full update, Consumers MAY send read-only attributes of the retrieved
resource and Service Provider MUST ignore any read-only attributes resource and the Service Provider MUST ignore any read-only
that are present in the payload of a PUT request. Unless otherwise attributes that are present in the payload of a PUT request. Unless
specified a successful PUT operation returns a 200 OK response code otherwise specified a successful PUT operation returns a 200 OK
and the entire Resource within the response body, enabling the response code and the entire Resource within the response body,
Consumer to correlate the Consumer's and Provider's views of the enabling the Consumer to correlate the Consumer's and Provider's
updated Resource. Example: views of the updated Resource. Example:
PUT /Users/2819c223-7f76-453a-919d-413861904646 PUT /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas":["urn:scim:schemas:core:1.0"], "schemas":["urn:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646", "id":"2819c223-7f76-453a-919d-413861904646",
"userName":"bjensen", "userName":"bjensen",
"externalId":"bjensen", "externalId":"bjensen",
"name":{ "name":{
"formatted":"Ms. Barbara J Jensen III", "formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen", "familyName":"Jensen",
"givenName":"Barbara", "givenName":"Barbara",
"middleName":"Jane" "middleName":"Jane"
}, },
"emails":[ "emails":[
skipping to change at page 21, line 5 skipping to change at page 19, line 45
"value":"bjensen@example.com" "value":"bjensen@example.com"
}, },
{ {
"value":"babs@jensen.org" "value":"babs@jensen.org"
} }
] ]
} }
The service responds with the entire, updated User The service responds with the entire, updated User
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
ETag: W/"b431af54f0671a2" ETag: W/"b431af54f0671a2"
Location:"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646" Location:"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646"
{ {
"schemas":["urn:scim:schemas:core:1.0"], "schemas":["urn:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646", "id":"2819c223-7f76-453a-919d-413861904646",
"userName":"bjensen", "userName":"bjensen",
"externalId":"bjensen", "externalId":"bjensen",
"name":{ "name":{
"formatted":"Ms. Barbara J Jensen III", "formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen", "familyName":"Jensen",
"givenName":"Barbara", "givenName":"Barbara",
"middleName":"Jane" "middleName":"Jane"
}, },
"emails":[ "emails":[
{ {
"value":"bjensen@example.com" "value":"bjensen@example.com"
}, },
{ {
"value":"babs@jensen.org" "value":"babs@jensen.org"
} }
], ],
"meta": { "meta": {
"resourceType","User", "resourceType":"User",
"created":"2011-08-08T04:56:22Z", "created":"2011-08-08T04:56:22Z",
"lastModified":"2011-08-08T08:00:12Z", "lastModified":"2011-08-08T08:00:12Z",
"location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"b431af54f0671a2\"" "version":"W\/\"b431af54f0671a2\""
} }
} }
3.3.2. Modifying with PATCH 3.3.2. Modifying with PATCH
PATCH is OPTIONAL. PATCH enables consumers to send only those PATCH is OPTIONAL. PATCH enables consumers to send only those
attributes requiring modification, reducing network and processing attributes requiring modification, reducing network and processing
overhead. Attributes may be deleted, replaced, merged, or added in a overhead. Attributes may be deleted, replaced, merged, or added in a
single request. single request.
The body of a PATCH request MUST contain a partial Resource with the The body of a PATCH request MUST contain a partial Resource with the
desired modifications. The server MUST return either a 200 OK desired modifications. The server MUST return either a 200 OK
skipping to change at page 23, line 5 skipping to change at page 21, line 49
have a value Sub-Attribute or that have a non-unique value Sub- have a value Sub-Attribute or that have a non-unique value Sub-
Attribute are matched by comparing all Sub-Attribute values from Attribute are matched by comparing all Sub-Attribute values from
the PATCH request body to the Sub-Attribute values of the the PATCH request body to the Sub-Attribute values of the
Resource. A delete operation is ignored if the attribute's name Resource. A delete operation is ignored if the attribute's name
is in the meta.attributes list. If the requested value to delete is in the meta.attributes list. If the requested value to delete
does not match a unique value on the Resource the server MAY does not match a unique value on the Resource the server MAY
return a HTTP 400 error. return a HTTP 400 error.
The following example shows how to add a member to a group: The following example shows how to add a member to a group:
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:schemas:core:1.0"], "schemas": ["urn:scim:schemas:core:2.0:Group"],
"members": [ "members": [
{ {
"display": "Babs Jensen", "display": "Babs Jensen",
"$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", "$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"value": "2819c223-7f76-453a-919d-413861904646" "value": "2819c223-7f76-453a-919d-413861904646"
} }
] ]
} }
The "display" Sub-Attribute in this request is optional since the The "display" Sub-Attribute in this request is optional since the
value attribute uniquely identifies the user to be added. If the value attribute uniquely identifies the user to be added. If the
user was already a member of this group, no changes should be made to user was already a member of this group, no changes should be made to
the Resource and a success response should be returned. The server the Resource and a success response should be returned. The server
responds with either the entire updated Group or no response body: responds with either the entire updated Group or no response body:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
ETag: W/"b431af54f0671a2" ETag: W/"b431af54f0671a2"
Location: "https://example.com/v1/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" Location: "https://example.com/v1/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce"
The following example shows how to remove a member from a group. As The following example shows how to remove a member from a group. As
with the previous example, the "display" Sub-Attribute is optional. with the previous example, the "display" Sub-Attribute is optional.
If the user was not a member of this group, no changes should be made If the user was not a member of this group, no changes should be made
to the Resource and a success response should be returned. to the Resource and a success response should be returned.
Note that server responses have been omitted for the rest of the Note that server responses have been omitted for the rest of the
PATCH examples. PATCH examples.
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:schemas:core:1.0"], "schemas": ["urn:scim:schemas:core:2.0:Group"],
"members": [ "members": [
{ {
"display": "Babs Jensen", "display": "Babs Jensen",
"$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", "$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"value": "2819c223-7f76-453a-919d-413861904646" "value": "2819c223-7f76-453a-919d-413861904646"
"operation": "delete" "operation": "delete"
} }
] ]
} }
The following example shows how to remove all members from a group: The following example shows how to remove all members from a group:
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:schemas:core:1.0"], "schemas": ["urn:scim:schemas:core:2.0:Group"],
"meta": { "meta": {
"attributes": [ "attributes": [
"members" "members"
] ]
} }
} }
The following example shows how to replace all of the members of a The following example shows how to replace all of the members of a
group with a different members list: group with a different members list:
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:schemas:core:1.0"], "schemas": ["urn:scim:schemas:core:2.0:Group"],
"meta": { "meta": {
"attributes": [ "attributes": [
"members" "members"
] ]
}, },
"members": [ "members": [
{ {
"display": "Babs Jensen", "display": "Babs Jensen",
"$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", "$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"value": "2819c223-7f76-453a-919d-413861904646" "value": "2819c223-7f76-453a-919d-413861904646"
}, },
{ {
"display": "James Smith", "display": "James Smith",
"$ref": "https://example.com/v1/Users/08e1d05d-121c-4561-8b96-473d93df9210", "$ref": "https://example.com/v1/Users/08e1d05d-121c-4561-8b96-473d93df9210",
"value": "08e1d05d-121c-4561-8b96-473d93df9210" "value": "08e1d05d-121c-4561-8b96-473d93df9210"
} }
] ]
} }
The following example shows how to add a member to and remove a The following example shows how to add a member to and remove a
member from a Group in a single request: member from a Group in a single request:
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:schemas:core:1.0"], "schemas": ["urn:scim:schemas:core:2.0:Group"],
"members": [ "members": [
{ {
"display": "Babs Jensen", "display": "Babs Jensen",
"$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", "$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"value": "2819c223-7f76-453a-919d-413861904646" "value": "2819c223-7f76-453a-919d-413861904646"
"operation": "delete" "operation": "delete"
}, },
{ {
"display": "James Smith", "display": "James Smith",
"$ref": "https://example.com/v1/Users/08e1d05d-121c-4561-8b96-473d93df9210", "$ref": "https://example.com/v1/Users/08e1d05d-121c-4561-8b96-473d93df9210",
"value": "08e1d05d-121c-4561-8b96-473d93df9210" "value": "08e1d05d-121c-4561-8b96-473d93df9210"
} }
] ]
} }
The following example shows how to change a User's primary email. If The following example shows how to change a User's primary email. If
the User already has the email address, it is made the primary the User already has the email address, it is made the primary
address and the current primary address (if present) is made non- address and the current primary address (if present) is made non-
primary. If the User does not already have the email address, it is primary. If the User does not already have the email address, it is
added and made the primary address. added and made the primary address.
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:schemas:core:1.0"], "schemas": ["urn:scim:schemas:core:2.0:User"],
"emails": [ "emails": [
{ {
"value": "bjensen@example.com", "value": "bjensen@example.com",
"primary": true "primary": true
} }
] ]
} }
The following example shows how to change a User's address. Since The following example shows how to change a User's address. Since
address does not have a value Sub-Attribute, the existing address address does not have a value Sub-Attribute, the existing address
must be removed and the modified address added. must be removed and the modified address added.
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:schemas:core:1.0"], "schemas": ["urn:scim:schemas:core:2.0:User"],
"addresses": [ "addresses": [
{ {
"type": "work", "type": "work",
"streetAddress": "100 Universal City Plaza", "streetAddress": "100 Universal City Plaza",
"locality": "Hollywood", "locality": "Hollywood",
"region": "CA", "region": "CA",
"postalCode": "91608", "postalCode": "91608",
"country": "US", "country": "US",
"formatted": "100 Universal City Plaza\nHollywood, CA 91608 US", "formatted": "100 Universal City Plaza\nHollywood, CA 91608 US",
"primary": true "primary": true
"operation": "delete" "operation": "delete"
}, },
{ {
"type": "work", "type": "work",
"streetAddress": "911 Universal City Plaza", "streetAddress": "911 Universal City Plaza",
"locality": "Hollywood", "locality": "Hollywood",
"region": "CA", "region": "CA",
"postalCode": "91608", "postalCode": "91608",
"country": "US", "country": "US",
"formatted": "911 Universal City Plaza\nHollywood, CA 91608 US", "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US",
"primary": true "primary": true
} }
] ]
} }
The following example shows how to change a User's nickname: The following example shows how to change a User's nickname:
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:schemas:core:1.0"], "schemas": ["urn:scim:schemas:core:2.0:User"],
"nickName": "Barbie" "nickName": "Barbie"
} }
The following example shows how to remove a User's nickname: The following example shows how to remove a User's nickname:
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:schemas:core:1.0"], "schemas": ["urn:scim:schemas:core:2.0:User"],
"meta": { "meta": {
"attributes": [ "attributes": [
"nickName" "nickName"
] ]
} }
} }
The following example shows how to change a User's familyName. This The following example shows how to change a User's familyName. This
only updates the familyName and formatted on the "name" complex only updates the familyName and formatted on the "name" complex
attribute. Any other name Sub-Attributes on the Resource remain attribute. Any other name Sub-Attributes on the Resource remain
unchanged. unchanged.
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:schemas:core:1.0"], "schemas": ["urn:scim:schemas:core:2.0:User"],
"name": { "name": {
"formatted": "Ms. Barbara J Jensen III", "formatted": "Ms. Barbara J Jensen III",
"familyName": "Jensen" "familyName": "Jensen"
} }
} }
The following example shows how to remove a complex Sub-Attribute and The following example shows how to remove a complex Sub-Attribute and
an extended schema attribute from a User. an extended schema attribute from a User.
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
skipping to change at page 29, line 18 skipping to change at page 27, line 27
an extended schema attribute from a User. an extended schema attribute from a User.
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:schemas:core:1.0"], "schemas": ["urn:scim:schemas:core:2.0:User"],
"meta": { "meta": {
"attributes": [ "attributes": [
"name.formatted", "name.formatted",
"urn:hr:schemas:user:age" "urn:hr:schemas:user:age"
] ]
} }
} }
3.4. Deleting Resources 3.4. Deleting Resources
skipping to change at page 30, line 4 skipping to change at page 28, line 15
DELETE /Users/2819c223-7f76-453a-919d-413861904646 DELETE /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"c310cd84f0281b7" If-Match: W/"c310cd84f0281b7"
Server Response: Server Response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Example: Consumer attempt to retrieve the previously deleted User Example: Consumer attempt to retrieve the previously deleted User
GET /Users/2819c223-7f76-453a-919d-413861904646 GET /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Server Response: Server Response:
HTTP/1.1 404 NOT FOUND HTTP/1.1 404 NOT FOUND
{ {
"Errors":[ "schemas": ["urn:scim:schemas:core:2.0:Error"],
{ "Errors":[
"description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", {
"code":"404" "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
} "code":"404"
] }
} ]
}
3.5. Bulk 3.5. Bulk
Bulk is OPTIONAL. The bulk operation enables Consumers to send a Bulk is OPTIONAL. The bulk operation enables Consumers to send a
potentially large collection of Resource operations in a single potentially large collection of Resource operations in a single
request. The body of a a bulk operation contains a set of HTTP request. The body of a a bulk operation contains a set of HTTP
Resource operations using one of the API supported HTTP methods; Resource operations using one of the API supported HTTP methods;
i.e., POST, PUT, PATCH or DELETE. i.e., POST, PUT, PATCH or DELETE.
Bulk requests are identified using the following URI:
'urn:scim:schemas:core:2.0:BulkRequest'. Bulk responses are
identified using the following URI:
'urn:scim:schemas:core:2.0:BulkResponse'. Bulk requests and bulk
responses share many attributes. Unless otherwise specified, each
attribute below is present in both bulk requests and bulk responses.
The following Singular Attribute is defined in addition to the common The following Singular Attribute is defined in addition to the common
attributes defined in SCIM core schema. attributes defined in SCIM core schema.
failOnErrors An Integer specifying the number of errors that the failOnErrors An Integer specifying the number of errors that the
Service Provider will accept before the operation is terminated Service Provider will accept before the operation is terminated
and an error response is returned. OPTIONAL. and an error response is returned. OPTIONAL in a request. Not
valid in a response.
The following Complex Multi-valued Attribute is defined in addition The following Complex Multi-valued Attribute is defined in addition
to the common attributes defined in core schema. to the common attributes defined in core schema.
Operations Defines operations within a bulk job. Each operation Operations Defines operations within a bulk job. Each operation
corresponds to a single HTTP request against a Resource endpoint. corresponds to a single HTTP request against a Resource endpoint.
REQUIRED. REQUIRED.
method The HTTP method of the current operation. Possible values method The HTTP method of the current operation. Possible values
are POST, PUT, PATCH or DELETE. REQUIRED. are POST, PUT, PATCH or DELETE. REQUIRED.
bulkId The transient identifier of a newly created Resource, bulkId The transient identifier of a newly created Resource,
unique within a bulk request and created by the Consumer. The unique within a bulk request and created by the Consumer.
bulkId serves as a surrogate Resource id enabling Consumers to The bulkId serves as a surrogate Resource id enabling
uniquely identify newly created Resources in the Response and Consumers to uniquely identify newly created Resources in
cross reference new Resources in and across operations within a the Response and cross reference new Resources in and across
bulk request. REQUIRED when method is POST. operations within a bulk request. REQUIRED when method is
POST.
version The current Resource version. Version is REQUIRED if the version The current Resource version. Version is REQUIRED if the
Service Provider supports ETags and the method is PUT, DELETE, Service Provider supports ETags and the method is PUT,
or PATCH. DELETE, or PATCH.
path The Resource's relative path. If the method is POST the path The Resource's relative path. If the method is POST the
value must specify a Resource type endpoint; e.g., /Users or value must specify a Resource type endpoint; e.g., /Users or
/Groups whereas all other method values must specify the path /Groups whereas all other method values must specify the
to a specific Resource; e.g., /Users/ path to a specific Resource; e.g., /Users/2819c223-7f76
2819c223-7f76-453a-919d-413861904646. REQUIRED in a request. -453a-919d-413861904646. REQUIRED in a request.
data The Resource data as it would appear for a single POST, PUT data The Resource data as it would appear for a single POST, PUT
or PATCH Resource operation. REQUIRED in a request when method or PATCH Resource operation. REQUIRED in a request when
is POST, PUT and PATCH. method is POST, PUT and PATCH.
location The Resource endpoint URL. REQUIRED in a response, location The Resource endpoint URL. REQUIRED in a response,
except in the event of a POST failure. except in the event of a POST failure.
status A complex type that contains information about the success status A complex type that contains information about the success
or failure of one operation within the bulk job. REQUIRED in a or failure of one operation within the bulk job. REQUIRED
response. in a response.
code The HTTP response code that would have been returned if a code The HTTP response code that would have been
a single HTTP request would have been used. REQUIRED. returned if a a single HTTP request would have been
used. REQUIRED.
description A human readable error message. REQUIRED when an description A human readable error message. REQUIRED when
error occurred. an error occurred.
If a bulk job is processed successfully the HTTP response code 200 OK If a bulk job is processed successfully the HTTP response code 200 OK
MUST be returned, otherwise an appropriate HTTP error code MUST be MUST be returned, otherwise an appropriate HTTP error code MUST be
returned. returned.
The Service Provider MUST continue performing as many changes as The Service Provider MUST continue performing as many changes as
possible and disregard partial failures. The Consumer MAY override possible and disregard partial failures. The Consumer MAY override
this behavior by specifying a value for failOnErrors attribute. The this behavior by specifying a value for failOnErrors attribute. The
failOnErrors attribute defines the number of errors that the Service failOnErrors attribute defines the number of errors that the Service
Provider should accept before failing the remaining operations Provider should accept before failing the remaining operations
skipping to change at page 32, line 28 skipping to change at page 31, line 11
would have been used. If an error occurred the status MUST also would have been used. If an error occurred the status MUST also
include the description attribute containing a human readable include the description attribute containing a human readable
explanation of the error. explanation of the error.
"status": { "status": {
"code": "201" "code": "201"
} }
The following is an example of a status in a failed operation. The following is an example of a status in a failed operation.
"status": { "status": {
"code": "400", "code": "400",
"description": "Request is unparseable, syntactically incorrect, or violates schema." "description": "Request is unparseable, syntactically incorrect, or violates schema."
} }
The following example shows how to add, update, and remove a user. The following example shows how to add, update, and remove a user.
The failOnErrors attribute is set to '1' indicating the Service The failOnErrors attribute is set to '1' indicating the Service
Provider should return on the first error. The POST operation's Provider should return on the first error. The POST operation's
bulkId value is set to 'qwerty' enabling the Consumer to match the bulkId value is set to 'qwerty' enabling the Consumer to match the
new User with the returned Resource id '92b725cd-9465-4e7d-8c16- new User with the returned Resource id '92b725cd-9465-4e7d-
01f8e146b87a'. 8c16-01f8e146b87a'.
POST /v1/Bulk POST /v1/Bulk
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
{ {
"schemas":[ "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"],
"urn:scim:schemas:core:1.0"
],
"failOnErrors":1, "failOnErrors":1,
"Operations":[ "Operations":[
{ {
"method":"POST", "method":"POST",
"path":"/Users", "path":"/Users",
"bulkId":"qwerty", "bulkId":"qwerty",
"data":{ "data":{
"schemas":[ "schemas": ["urn:scim:schemas:core:2.0:User"],
"urn:scim:schemas:core:1.0"
],
"userName":"Alice" "userName":"Alice"
} }
}, },
{ {
"method":"PUT", "method":"PUT",
"path":"/Users/b7c14771-226c-4d05-8860-134711653041", "path":"/Users/b7c14771-226c-4d05-8860-134711653041",
"version":"W\/\"3694e05e9dff591\"", "version":"W\/\"3694e05e9dff591\"",
"data":{ "data":{
"schemas":[ "schemas": ["urn:scim:schemas:core:2.0:User"],
"urn:scim:schemas:core:1.0"
],
"id":"b7c14771-226c-4d05-8860-134711653041", "id":"b7c14771-226c-4d05-8860-134711653041",
"userName":"Bob" "userName":"Bob"
} }
}, },
{ {
"method":"PATCH", "method":"PATCH",
"path":"/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", "path":"/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"version":"W\/\"edac3253e2c0ef2\"", "version":"W\/\"edac3253e2c0ef2\"",
"data":{ "data":{
"schemas":[ "schemas":["urn:scim:schemas:core:2.0:User"],
"urn:scim:schemas:core:1.0"
],
"id":"5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", "id":"5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"userName":"Dave", "userName":"Dave",
"meta":{ "meta":{
"attributes":[ "attributes":[
"nickName" "nickName"
] ]
} }
} }
}, },
{ {
skipping to change at page 34, line 4 skipping to change at page 32, line 28
"nickName" "nickName"
] ]
} }
} }
}, },
{ {
"method":"DELETE", "method":"DELETE",
"path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"version":"W\/\"0ee8add0a938e1a\"" "version":"W\/\"0ee8add0a938e1a\""
} }
] ]
} }
The Service Provider returns the following response. The Service Provider returns the following response.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
{
"schemas": ["urn:scim:schemas:core:2.0:BulkResponse"],
"Operations": [
{
"location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST",
"bulkId": "qwerty",
"version": "W\/\"oY4m4wn58tkVjJxK\"",
"status": {
"code": "201"
}
},
{
"location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT",
"version": "W\/\"huJj29dMNgu3WXPD\"",
"status": {
"code": "200"
}
},
{
"location": "https://example.com/v1/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH",
"version": "W\/\"huJj29dMNgu3WXPD\"",
"status": {
"code": "200"
}
},
{
"location": "https://example.com/v1/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE",
"status": {
"code": "200"
}
}
]
}
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"Operations": [
{
"location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST",
"bulkId": "qwerty",
"version": "W\/\"oY4m4wn58tkVjJxK\"",
"status": {
"code": "201"
}
},
{
"location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT",
"version": "W\/\"huJj29dMNgu3WXPD\"",
"status": {
"code": "200"
}
},
{
"location": "https://example.com/v1/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH",
"version": "W\/\"huJj29dMNgu3WXPD\"",
"status": {
"code": "200"
}
},
{
"location": "https://example.com/v1/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE",
"status": {
"code": "200"
}
}
]
}
The following response is returned if an error occurred when The following response is returned if an error occurred when
attempting to create the User 'Alice'. The Service Provider stops attempting to create the User 'Alice'. The Service Provider stops
processing the bulk operation and immediately returns a response to processing the bulk operation and immediately returns a response to
the Consumer. The response contains the error and any successful the Consumer. The response contains the error and any successful
results prior to the error. results prior to the error.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
{ {
"schemas": [ "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"],
"urn:scim:schemas:core:1.0" "Operations": [
], {
"Operations": [ "method": "POST",
{ "bulkId": "qwerty",
"method": "POST", "status": {
"bulkId": "qwerty", "code": "400",
"status": { "description": "Request is unparseable, syntactically incorrect, or violates schema."
"code": "400", }
"description": "Request is unparseable, syntactically incorrect, or violates schema." }
} ]
} }
]
}
If the failOnErrors attribute is not specified or the Service If the failOnErrors attribute is not specified or the Service
Provider has not reached the error limit defined by the Consumer the Provider has not reached the error limit defined by the Consumer the
Service Provider will continue to process all operations. The Service Provider will continue to process all operations. The
following is an example in which all operations failed. following is an example in which all operations failed.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
{ {
"schemas": [ "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"],
"urn:scim:schemas:core:1.0" "Operations": [
], {
"Operations": [ "method": "POST",
{ "bulkId": "qwerty",
"method": "POST", "status": {
"bulkId": "qwerty", "code": "400",
"status": { "description": "Request is unparseable, syntactically incorrect, or violates schema."
"code": "400", }
"description": "Request is unparseable, syntactically incorrect, or violates schema." },
} {
}, "location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041",
{ "method": "PUT",
"location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041", "status": {
"method": "PUT", "code": "412",
"status": { "description": "Failed to update as user changed on the server since you last retrieved it."
"code": "412", }
"description": "Failed to update as user changed on the server since you last retrieved it." },
} {
}, "location": "https://example.com/v1/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
{ "method": "PATCH",
"location": "https://example.com/v1/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", "status": {
"method": "PATCH", "code": "412",
"status": { "description": "Failed to update as user changed on the server since you last retrieved it."
"code": "412", }
"description": "Failed to update as user changed on the server since you last retrieved it." },
} {
}, "location": "https://example.com/v1/Users/e9025315-6bea-44e1-899c-1e07454e468b",
{ "method": "DELETE",
"location": "https://example.com/v1/Users/e9025315-6bea-44e1-899c-1e07454e468b", "status": {
"method": "DELETE", "code": "404",
"status": { "description": "Specified resource; e.g., User, does not exist."
"code": "404", }
"description": "Specified resource; e.g., User, does not exist." }
} ]
} }
]
}
The Consumer can, within one bulk operation, create a new User, a new The Consumer can, within one bulk operation, create a new User, a new
Group and add the newly created User to the newly created Group. In Group and add the newly created User to the newly created Group. In
order to add the new User to the Group the Consumer must use the order to add the new User to the Group the Consumer must use the
surrogate id attribute, bulkId, to reference the User. The bulkId surrogate id attribute, bulkId, to reference the User. The bulkId
attribute value must be pre-pended with the literal "bulkId:"; e.g., attribute value must be pre-pended with the literal "bulkId:"; e.g.,
if the bulkId is 'qwerty' the value is "bulkId:qwerty". The Service if the bulkId is 'qwerty' the value is "bulkId:qwerty". The Service
Provider MUST replace the string "bulkId:qwerty" with the permanent Provider MUST replace the string "bulkId:qwerty" with the permanent
Resource id once created. Resource id once created.
skipping to change at page 37, line 19 skipping to change at page 35, line 41
Group with the displayName 'Tour Guides' with Alice as a member. Group with the displayName 'Tour Guides' with Alice as a member.
POST /v1/Bulk POST /v1/Bulk
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
{ {
"schemas": [ "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"],
"urn:scim:schemas:core:1.0"
],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"path": "/Users", "path": "/Users",
"bulkId": "qwerty", "bulkId": "qwerty",
"data": { "data": {
"schemas": [ "schemas": ["urn:scim:schemas:core:2.0:User"],
"urn:scim:schemas:core:1.0"
],
"userName": "Alice" "userName": "Alice"
} }
}, },
{ {
"method": "POST", "method": "POST",
"path": "/Groups", "path": "/Groups",
"bulkId": "ytrewq", "bulkId": "ytrewq",
"data": { "data": {
"schemas": [ "schemas": ["urn:scim:schemas:core:2.0:Group"],
"urn:scim:schemas:core:1.0"
],
"displayName": "Tour Guides", "displayName": "Tour Guides",
"members": [ "members": [
{ {
"type": "user", "type": "user",
"value": "bulkId:qwerty" "value": "bulkId:qwerty"
} }
] ]
} }
} }
] ]
} }
The Service Provider returns the following response. The Service Provider returns the following response.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
{ {
"schemas": [ "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"],
"urn:scim:schemas:core:1.0" "Operations": [
], {
"Operations": [ "location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
{ "method": "POST",
"location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", "bulkId": "qwerty",
"method": "POST", "version": "W\/\"4weymrEsh5O6cAEK\"",
"bulkId": "qwerty", "status": {
"version": "W\/\"4weymrEsh5O6cAEK\"", "code": "201"
"status": { }
"code": "201" },
} {
}, "location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
{ "method": "POST",
"location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", "bulkId": "ytrewq",
"method": "POST", "version": "W\/\"lha5bbazU3fNvfe5\"",
"bulkId": "ytrewq", "status": {
"version": "W\/\"lha5bbazU3fNvfe5\"", "code": "201"
"status": { }
"code": "201" }
}
}
]
}
A subsequent request for the 'Tour Guides' Group ('e9e30dba-f08f- ]
4109-8486-d5c6a331660a') returns the following: }
A subsequent request for the 'Tour Guides' Group ('e9e30dba-
f08f-4109-8486-d5c6a331660a') returns the following:
GET /v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a GET /v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Location: https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a Location: https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
ETag: W/"lha5bbazU3fNvfe5" ETag: W/"lha5bbazU3fNvfe5"
{ {
"schemas":["urn:scim:schemas:core:1.0"], "schemas": ["urn:scim:schemas:core:2.0:Group"],
"id": "e9e30dba-f08f-4109-8486-d5c6a331660a", "id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
"displayName": "Tour Guides", "displayName": "Tour Guides",
"meta": { "meta": {
"created":"2011-08-01T18:29:49.793Z", "resourceType": "Group",
"lastModified":"2011-08-01T20:31:02.315Z", "created": "2011-08-01T18:29:49.793Z",
"location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", "lastModified": "2011-08-01T20:31:02.315Z",
"version": "W\/\"lha5bbazU3fNvfe5\"" "location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
}, "version": "W\/\"lha5bbazU3fNvfe5\""
"members": [ },
{ "members": [
"value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", {
"$ref": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a",
"type": "User" "$ref": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
} "type": "User"
] }
} ]
}
Extensions that include references to other Resources MUST be handled Extensions that include references to other Resources MUST be handled
in the same way by the Service Provider. The following example uses in the same way by the Service Provider. The following example uses
the bulkId attribute within the enterprise extension managerId the bulkId attribute within the enterprise extension managerId
attribute. attribute.
POST /v1/Bulk POST /v1/Bulk
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
{ {
"schemas": [ "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"],
"urn:scim:schemas:core:1.0"
],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"path": "/Users", "path": "/Users",
"bulkId": "qwerty", "bulkId": "qwerty",
"data": { "data": {
"schemas": [ "schemas": ["urn:scim:schemas:core:2.0:User"],
"urn:scim:schemas:core:1.0"
],
"userName": "Alice" "userName": "Alice"
} }
}, },
{ {
"method": "POST", "method": "POST",
"path": "/Users", "path": "/Users",
"bulkId": "ytrewq", "bulkId": "ytrewq",
"data": { "data": {
"schemas": [ "schemas": [
"urn:scim:schemas:core:1.0", "urn:scim:schemas:core:2.0:User",
"urn:scim:schemas:extension:enterprise:1.0" "urn:scim:schemas:extension:enterprise:2.0:User"
], ],
"userName": "Bob", "userName": "Bob",
"urn:scim:schemas:extension:enterprise:1.0": { "urn:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "11250", "employeeNumber": "11250",
"manager": { "manager": {
"managerId": "batchId:qwerty", "managerId": "batchId:qwerty",
"displayName": "Alice" "displayName": "Alice"
} }
} }
} }
} }
] ]
} }
skipping to change at page 42, line 13 skipping to change at page 39, line 11
following example exhibits the potential conflict. following example exhibits the potential conflict.
POST /v1/Bulk POST /v1/Bulk
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
{ {
"schemas": [ "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"],
"urn:scim:schemas:core:1.0"
],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"path": "/Groups", "path": "/Groups",
"bulkId": "qwerty", "bulkId": "qwerty",
"data": { "data": {
"schemas": [ "schemas": ["urn:scim:schemas:core:2.0:Group"],
"urn:scim:schemas:core:1.0"
],
"displayName": "Group A", "displayName": "Group A",
"members": [ "members": [
{ {
"type": "group", "type": "group",
"value": "bulkId:ytrewq" "value": "bulkId:ytrewq"
} }
] ]
} }
}, },
{ {
"method": "POST", "method": "POST",
"path": "/Groups", "path": "/Groups",
"bulkId": "ytrewq", "bulkId": "ytrewq",
"data": { "data": {
"schemas": [ "schemas": ["urn:scim:schemas:core:2.0:Group"],
"urn:scim:schemas:core:1.0"
],
"displayName": "Group B", "displayName": "Group B",
"members": [ "members": [
{ {
"type": "group", "type": "group",
"value": "bulkId:qwerty" "value": "bulkId:qwerty"
} }
] ]
} }
} }
] ]
skipping to change at page 43, line 4 skipping to change at page 39, line 45
"members": [ "members": [
{ {
"type": "group", "type": "group",
"value": "bulkId:qwerty" "value": "bulkId:qwerty"
} }
] ]
} }
} }
] ]
} }
If the Service Provider resolved the above circular references the If the Service Provider resolved the above circular references the
following is returned from a subsequent GET request. following is returned from a subsequent GET request.
GET /v1/Groups?filter=displayName sw 'Group' GET /v1/Groups?filter=displayName sw 'Group'
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
{ {
"totalResults": 2, "schemas": ["urn:scim:schemas:core:2.0:ListResponse"],
"schemas": [ "totalResults": 2,
"urn:scim:schemas:core:1.0" "Resources": [
], {
"Resources": [ "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
{ "schemas": ["urn:scim:schemas:core:2.0:Group"],
"id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", "displayName": "Group A",
"schemas": [ "meta": {
"urn:scim:schemas:core:1.0" "resourceType": "Group",
], "created": "2011-08-01T18:29:49.793Z",
"displayName": "Group A", "lastModified": "2011-08-01T18:29:51.135Z",
"meta": { "location": "https://example.com/v1/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"created":"2011-08-01T18:29:49.793Z", "version": "W\/\"mvwNGaxB5SDq074p\""
"lastModified":"2011-08-01T18:29:51.135Z", },
"location":"https://example.com/v1/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", "members": [
"version":"W\/\"mvwNGaxB5SDq074p\"" {
}, "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"members": [ "$ref": "https://example.com/v1/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
{ "type": "Group"
"value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", }
"$ref": "https://example.com/v1/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", ]
"type": "Group" },
} {
] "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
}, "schemas": ["urn:scim:schemas:core:2.0:Group"],
{ "displayName": "Group B",
"id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", "meta": {
"schemas": [ "resourceType": "Group",
"urn:scim:schemas:core:1.0" "created": "2011-08-01T18:29:50.873Z",
], "lastModified": "2011-08-01T18:29:50.873Z",
"displayName": "Group B", "location": "https://example.com/v1/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"meta": { "version": "W\/\"wGB85s2QJMjiNnuI\""
"created":"2011-08-01T18:29:50.873Z", },
"lastModified":"2011-08-01T18:29:50.873Z", "members": [
"location":"https://example.com/v1/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", {
"version":"W\/\"wGB85s2QJMjiNnuI\"" "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
}, "$ref": "https://example.com/v1/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"members": [ "type": "Group"
{
"value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", }
"$ref": "https://example.com/v1/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", ]
"type": "Group" }
} ]
] }
}
]
}
The Service Provider MUST define the maximum number of operations and The Service Provider MUST define the maximum number of operations and
maximum payload size a Consumer may send in a single request. If maximum payload size a Consumer may send in a single request. If
either limits are exceeded the Service Provider MUST return the HTTP either limits are exceeded the Service Provider MUST return the HTTP
response code 413 Request Entity Too Large. The returned response response code 413 Request Entity Too Large. The returned response
MUST specify the limit exceeded in the body of the error response. MUST specify the limit exceeded in the body of the error response.
The following example the Consumer sent a request exceeding the The following example the Consumer sent a request exceeding the
Service Provider's max payload size of 1 megabyte. Service Provider's max payload size of 1 megabyte.
POST /v1/Bulk POST /v1/Bulk
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: 4294967296 Content-Length: 4294967296
... ...
HTTP/1.1 413 Request Entity Too Large HTTP/1.1 413 Request Entity Too Large
Content-Type: application/json Content-Type: application/json
Location: https://example.com/v1/Bulk/yfCrVJhFIJagAHj8 Location: https://example.com/v1/Bulk/yfCrVJhFIJagAHj8
{
"schemas":["urn:scim:schemas:core:2.0:Error"],
"Errors":[
{
"description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).",
"code":"413"
}
]
}
{
"Errors":[
{
"description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).",
"code":"413"
}
]
}
3.6. Data Input/Output Formats 3.6. Data Input/Output Formats
Consumers MUST specify the format in which the data is submitted via Consumers MUST specify the format in which the data is submitted via
the HTTP header content-type and MAY specify the desired response the HTTP header content-type [10] and MAY specify the desired
data format via an HTTP Accept Header; e.g.,"Accept: application/ response data format via an HTTP Accept Header; e.g.,"Accept:
json" or via URI suffix; e.g., application/json" or via URI suffix; e.g.,
GET /Users/2819c223-7f76-453a-919d-413861904646.json GET /Users/2819c223-7f76-453a-919d-413861904646.json
Host: example.com Host: example.com
Service Providers MUST support the Accept Headers "Accept: Service Providers MUST support the Accept Headers "Accept:
application/json" for JSON [5]. The format defaults to JSON if no application/json" for JSON [11]. The format defaults to JSON if no
format is specified. format is specified.
Singular attributes are encoded as string name-value-pairs in JSON; Singular attributes are encoded as string name-value-pairs in JSON;
e.g., e.g.,
"attribute": "value" "attribute": "value"
Multi-valued attributes in JSON are encoded as arrays; e.g., Multi-valued attributes in JSON are encoded as arrays; e.g.,
"attributes": [ "value1", "value2" ] "attributes": [ "value1", "value2" ]
skipping to change at page 45, line 37 skipping to change at page 42, line 38
Elements with nested elements are represented as objects in JSON; Elements with nested elements are represented as objects in JSON;
e.g, e.g,
"attribute": { "subattribute1": "value1", "subattribute2": "value2" } "attribute": { "subattribute1": "value1", "subattribute2": "value2" }
3.7. Additional retrieval query parameters 3.7. Additional retrieval query parameters
Consumers MAY request a partial Resource representation on any Consumers MAY request a partial Resource representation on any
operation that returns a Resource within the response by specifying operation that returns a Resource within the response by specifying
the URL query parameter 'attributes'. When specified, each Resource the URL query parameter 'attributes'. When specified, each Resource
returned MUST contain the minimal set of Resource attributes and, returned MUST contain the minimal set of Resource attributes and MUST
MUST contain no other attributes or Sub-Attributes than those contain no other attributes or Sub-Attributes than those explicitly
explicitly requested. The query parameter attributes value is a requested. The query parameter attributes value is a comma separated
comma separated list of Resource attribute names in standard, list of Resource attribute names in standard attribute notation
attribute notation (Section 3.8) form (e.g. userName, name, emails). (Section 3.8) form (e.g. userName, name, emails).
GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Giving the response Giving the response
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646 Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"a330bc54f0671c9" ETag: W/"a330bc54f0671c9"
{ {
"schemas":["urn:scim:schemas:core:1.0"], "schemas":["urn:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646", "id":"2819c223-7f76-453a-919d-413861904646",
"userName":"bjensen", "userName":"bjensen",
"meta":{ "meta":{
"created":"2011-08-01T18:29:49.793Z", "resourceType": "User",
"lastModified":"2011-08-01T18:29:49.793Z", "created":"2011-08-01T18:29:49.793Z",
"location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", "lastModified":"2011-08-01T18:29:49.793Z",
"version":"W\/\"a330bc54f0671c9\"" "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
} "version":"W\/\"a330bc54f0671c9\""
} }
}
3.8. Attribute Notation 3.8. Attribute Notation
All operations share a common scheme for referencing simple and All operations share a common scheme for referencing simple and
complex attributes. In general, attributes are identified by complex attributes. In general, attributes are identified by
prefixing the attribute name with its schema URN separated by a ':' prefixing the attribute name with its schema URN separated by a ':'
character; e.g., the core User Resource attribute 'userName' is character; e.g., the core User Resource attribute 'userName' is
identified as 'urn:scim:schemas:core:1.0:userName'. Consumers MAY identified as 'urn:scim:schemas:core:2.0:userName'. Consumers MAY
omit core schema attribute URN prefixes though MUST fully qualify omit core schema attribute URN prefixes though MUST fully qualify
extended attributes with the associated Resource URN; e.g., the extended attributes with the associated Resource URN; e.g., the
attribute 'age' defined in 'urn:hr:schemas:user' is fully encoded as attribute 'age' defined in 'urn:hr:schemas:user' is fully encoded as
'urn:hr:schemas:user:age'. A Complex attributes' Sub-Attributes are 'urn:hr:schemas:user:age'. A Complex attributes' Sub-Attributes are
referenced via nested, dot ('.') notation; i.e., {urn}:{Attribute referenced via nested, dot ('.') notation; i.e., {urn}:{Attribute
name}.{Sub-Attribute name}. For example, the fully qualified path name}.{Sub-Attribute name}. For example, the fully qualified path
for a User's givenName is urn:scim:schemas:core:1.0:name.givenName for a User's givenName is urn:scim:schemas:core:2.0:name.givenName
All facets (URN, attribute and Sub-Attribute name) of the fully All facets (URN, attribute and Sub-Attribute name) of the fully
encoded Attribute name are case insensitive. encoded Attribute name are case insensitive.
3.9. HTTP Response Codes 3.9. HTTP Response Codes
The SCIM Protocol uses the response status codes defined in HTTP [6] The SCIM Protocol uses the response status codes defined in HTTP [12]
to indicate operation success or failure. In addition to returning a to indicate operation success or failure. In addition to returning a
HTTP response code implementers MUST return the errors in the body of HTTP response code implementers MUST return the errors in the body of
the response in the client requested format containing the error the response in the client requested format containing the error
response and, per the HTTP specification, human-readable response and, per the HTTP specification, human-readable
explanations. Implementers SHOULD handle the identified errors as explanations. Error responses are identified using the following
described below. URI: 'urn:scim:schemas:core:2.0:Error'. The following multi-valued
attribute is defined in addition to those attributes defined in SCIM
Core Schema:
+--------------+---------------------------+------------------------+ Errors The list of errors encountered by the Service Provider. The
| Code | Applicability | Suggested Explanation | value attribute is a complex type with the following sub-
+--------------+---------------------------+------------------------+ attributes.
| 400 BAD | GET,POST,PUT,PATCH,DELETE | Request is |
| REQUEST | | unparseable, | description A human-readable explanation of the error. REQUIRED.
| | | syntactically |
| | | incorrect, or violates | code A string indicating the HTTP response code. REQUIRED.
| | | schema |
| 401 | GET,POST,PUT,PATCH,DELETE | Authorization failure | Implementers SHOULD handle the identified errors as described below.
| UNAUTHORIZED | | |
| 403 | GET,POST,PUT,PATCH,DELETE | Server does not | +----------------+---------------------------+----------------------+
| FORBIDDEN | | support requested | | Code | Applicability | Suggested |
| | | operation | | | | Explanation |
| 404 NOT | GET,PUT,PATCH,DELETE | Specified resource; | +----------------+---------------------------+----------------------+
| FOUND | | e.g., User, does not | | 400 BAD | GET,POST,PUT,PATCH,DELETE | Request is |
| | | exist | | REQUEST | | unparseable, |
| 409 CONFLICT | POST, PUT,PATCH,DELETE | The specified version | | | | syntactically |
| | | number does not match | | | | incorrect, or |
| | | the resource's latest | | | | violates schema |
| | | version number or a | | 401 | GET,POST,PUT,PATCH,DELETE | Authorization |
| | | Service Provider | | UNAUTHORIZED | | failure |
| | | refused to create a | | 403 FORBIDDEN | GET,POST,PUT,PATCH,DELETE | Server does not |
| | | new, duplicate | | | | support requested |
| | | resource | | | | operation |
| 412 | PUT,PATCH,DELETE | Failed to update as | | 404 NOT FOUND | GET,PUT,PATCH,DELETE | Specified resource; |
| PRECONDITION | | Resource {id} changed | | | | e.g., User, does not |
| FAILED | | on the server last | | | | exist |
| | | retrieved | | 409 CONFLICT | POST, PUT,PATCH,DELETE | The specified |
| 413 REQUEST | POST | {"maxOperations": | | | | version number does |
| ENTITY TOO | | 1000,"maxPayload": | | | | not match the |
| LARGE | | 1048576} | | | | resource's latest |
| 500 INTERNAL | GET,POST,PUT,PATCH,DELETE | An internal error. | | | | version number or a |
| SERVER ERROR | | Implementers SHOULD | | | | Service Provider |
| | | provide descriptive | | | | refused to create a |
| | | debugging advice | | | | new, duplicate |
| 501 NOT | GET,POST,PUT,PATCH,DELETE | Service Provider does | | | | resource |
| IMPLEMENTED | | not support the | | 412 | PUT,PATCH,DELETE | Failed to update as |
| | | request operation; | | PRECONDITION | | Resource {id} |
| | | e.g., PATCH | | FAILED | | changed on the |
+--------------+---------------------------+------------------------+ | | | server last |
| | | retrieved |
| 413 REQUEST | POST | {"maxOperations": |
| ENTITY TOO | | 1000,"maxPayload": |
| LARGE | | 1048576} |
| 500 INTERNAL | GET,POST,PUT,PATCH,DELETE | An internal error. |
| SERVER ERROR | | Implementers SHOULD |
| | | provide descriptive |
| | | debugging advice |
| 501 NOT | GET,POST,PUT,PATCH,DELETE | Service Provider |
| IMPLEMENTED | | does not support the |
| | | request operation; |
| | | e.g., PATCH |
+----------------+---------------------------+----------------------+
Table 7: Defined error cases Table 7: Defined error cases
Error example in response to a non-existent GET request. Error example in response to a non-existent GET request.
HTTP/1.1 404 NOT FOUND HTTP/1.1 404 NOT FOUND
{ {
"Errors":[ "schemas": ["urn:scim:schemas:core:2.0:Error"],
{ "Errors":[
"description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", {
"code":"404" "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
} "code":"404"
] }
} ]
}
3.10. API Versioning 3.10. API Versioning
The Base URL MAY be appended with a version identifier as a separate The Base URL MAY be appended with a version identifier as a separate
segment in the URL path. At this time the only valid identifier is segment in the URL path. At this time the only valid identifier is
'v1'. If specified, the version identifier MUST appear in the URL 'v1'. If specified, the version identifier MUST appear in the URL
path immediately preceding the Resource endpoint and conform to the path immediately preceding the Resource endpoint and conform to the
following scheme: the character 'v' followed by the desired SCIM following scheme: the character 'v' followed by the desired SCIM
version number; e.g., a version 'v1' User request is specified as version number; e.g., a version 'v1' User request is specified as /v1
/v1/Users. When specified Service Providers MUST perform the /Users. When specified Service Providers MUST perform the operation
operation using the desired version or reject the request. When using the desired version or reject the request. When omitted
omitted Service Providers SHOULD perform the operation using the most Service Providers SHOULD perform the operation using the most recent
recent API supported by the Service Provider. API supported by the Service Provider.
3.11. Versioning Resources 3.11. Versioning Resources
The API supports resource versioning via standard,HTTP ETags. The API supports resource versioning via standard HTTP ETags [13].
Service providers MAY support weak ETags as the preferred mechanism Service providers MAY support weak ETags as the preferred mechanism
for performing conditional retrievals and ensuring Consumers do not for performing conditional retrievals and ensuring Consumers do not
inadvertently overwrite each others changes, respectively. When inadvertently overwrite each others changes, respectively. When
supported SCIM ETags MUST be specified as an HTTP header and SHOULD supported SCIM ETags MUST be specified as an HTTP header and SHOULD
be specified within the 'version' attribute contained in the be specified within the 'version' attribute contained in the
Resource's 'meta' attribute. Resource's 'meta' attribute.
Example: Example:
POST /Users HTTP/1.1 POST /Users HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/json Content-Type: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
{ {
"schemas":["urn:scim:schemas:core:1.0"], "schemas":["urn:scim:schemas:core:2.0:User"],
"userName":"bjensen", "userName":"bjensen",
"externalId":"bjensen", "externalId":"bjensen",
"name":{ "name":{
"formatted":"Ms. Barbara J Jensen III", "formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen", "familyName":"Jensen",
"givenName":"Barbara" "givenName":"Barbara"
} }
} }
The server responds with an ETag in the response header and meta The server responds with an ETag in the response header and meta
structure. structure.
HTTP/1.1 201 Created HTTP/1.1 201 Created
Content-Type: application/json Content-Type: application/json
Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646 Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1" ETag: W/"e180ee84f0671b1"
{ {
"schemas":["urn:scim:schemas:core:1.0"], "schemas":["urn:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646", "id":"2819c223-7f76-453a-919d-413861904646",
"meta":{ "meta":{
"created":"2011-08-01T21:32:44.882Z", "resourceType":"User",
"lastModified":"2011-08-01T21:32:44.882Z", "created":"2011-08-01T21:32:44.882Z",
"location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", "lastModified":"2011-08-01T21:32:44.882Z",
"version":"W\/\"e180ee84f0671b1\"" "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
}, "version":"W\/\"e180ee84f0671b1\""
"name":{ },
"formatted":"Ms. Barbara J Jensen III", "name":{
"familyName":"Jensen", "formatted":"Ms. Barbara J Jensen III",
"givenName":"Barbara" "familyName":"Jensen",
}, "givenName":"Barbara"
"userName":"bjensen" },
} "userName":"bjensen"
}
With the returned ETag, Consumers MAY choose to retrieve the Resource With the returned ETag, Consumers MAY choose to retrieve the Resource
only if the Resource has been modified. only if the Resource has been modified.
Conditional retrieval example using If-None-Match header: Conditional retrieval example using If-None-Match [14] header:
GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-None-Match: W/"e180ee84f0671b1" If-None-Match: W/"e180ee84f0671b1"
If the Resource has not changed the Service Provider simply returns If the Resource has not changed the Service Provider simply returns
an empty body with a 304 "Not Modified" response code. an empty body with a 304 "Not Modified" response code.
If the Service Providers supports versioning of resources the If the Service Providers supports versioning of resources the
Consumer MUST supply an If-Match header for PUT and PATCH operations Consumer MUST supply an If-Match [15] header for PUT and PATCH
to ensure that the requested operation succeeds only if the supplied operations to ensure that the requested operation succeeds only if
ETag matches the latest Service Provider Resource; e.g., If-Match: the supplied ETag matches the latest Service Provider Resource; e.g.,
W/"e180ee84f0671b1" If-Match: W/"e180ee84f0671b1"
3.12. HTTP Method Overloading 3.12. HTTP Method Overloading
In recognition that some clients, servers and firewalls prevent PUT, In recognition that some clients, servers and firewalls prevent PUT,
PATCH and DELETE operations a client MAY override the POST operation PATCH and DELETE operations a client MAY override the POST operation
by specifying the custom header "X-HTTP-Method-Override" with the by specifying the custom header "X-HTTP-Method-Override" with the
desired PUT, PATCH, DELETE operation. For example: desired PUT, PATCH, DELETE operation. For example:
POST /Users/2819c223-7f76-453a-919d-413861904646 POST /Users/2819c223-7f76-453a-919d-413861904646
X-HTTP-Method-Override: DELETE X-HTTP-Method-Override: DELETE
4. Multi-Tenancy 4. Multi-Tenancy
skipping to change at page 52, line 32 skipping to change at page 50, line 11
The Service Provider may choose to implement SCIM ids which are The Service Provider may choose to implement SCIM ids which are
unique across all Resources for all Tenants, but this is not unique across all Resources for all Tenants, but this is not
required. required.
The externalId, defined by the Consumer, is required to be unique The externalId, defined by the Consumer, is required to be unique
ONLY within the Resources associated with the associated Tenant. ONLY within the Resources associated with the associated Tenant.
5. Security Considerations 5. Security Considerations
The SCIM Protocol is based on HTTP and thus subject to the security The SCIM Protocol is based on HTTP and thus subject to the security
considerations found in Section 15 of [RFC2616]. SCIM Resources considerations found in Section 15 of [RFC2616] [16]. SCIM Resources
(e.g., Users and Groups) can contain sensitive information. (e.g., Users and Groups) can contain sensitive information.
Therefore, SCIM Consumers and Service Providers MUST implement TLS. Therefore, SCIM Consumers and Service Providers MUST implement TLS.
Which version(s) ought to be implemented will vary over time, and Which version(s) ought to be implemented will vary over time, and
depend on the widespread deployment and known security depend on the widespread deployment and known security
vulnerabilities at the time of implementation. At the time of this vulnerabilities at the time of implementation. At the time of this
writing, TLS version 1.2 [RFC5246 [7]] is the most recent version, writing, TLS version 1.2 [RFC5246 [17]] is the most recent version,
but has very limited actual deployment, and might not be readily but has very limited actual deployment, and might not be readily
available in implementation toolkits. TLS version 1.0 [RFC2246 [7]] available in implementation toolkits. TLS version 1.0 [RFC2246 [18]]
is the most widely deployed version, and will give the broadest is the most widely deployed version, and will give the broadest
interoperability. interoperability.
6. Contributors 6. Contributors
Samuel Erdtman (samuel@erdtman.se) Samuel Erdtman (samuel@erdtman.se)
Patrick Harding (pharding@pingidentity.com) Patrick Harding (pharding@pingidentity.com)
7. Acknowledgments 7. Acknowledgments
The editor would like to thank the participants in the the SCIM The editor would like to thank the participants in the the SCIM
working group for their support of this specification. working group for their support of this specification.
8. References
Authors' Addresses Authors' Addresses
Trey Drake (editor) Trey Drake (editor)
UnboundID UnboundID
Email: trey.drake@unboundid.com Email: trey.drake@unboundid.com
Chuck Mortimore Chuck Mortimore
SalesForce SalesForce
 End of changes. 134 change blocks. 
880 lines changed or deleted 938 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/