draft-ietf-scim-api-02.txt   draft-ietf-scim-api-03.txt 
Network Working Group T. Drake, Ed. Network Working Group K. Grizzle
Internet-Draft UnboundID Internet-Draft SailPoint
Intended status: Standards Track C. Mortimore Intended status: Standards Track P. Hunt, Ed.
Expires: March 03, 2014 SalesForce Expires: August 16, 2014 Oracle
M. Ansari M. Ansari
Cisco Cisco
K. Grizzle
SailPoint
E. Wahlstroem E. Wahlstroem
Technology Nexus Technology Nexus
August 30, 2013 C. Mortimore
Salesforce
February 12, 2014
System for Cross-Domain Identity Management:Protocol System for Cross-Domain Identity Management:Protocol
draft-ietf-scim-api-02 draft-ietf-scim-api-03
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
skipping to change at page 1, line 47 skipping to change at page 1, line 47
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 March 03, 2014. This Internet-Draft will expire on August 16, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2014 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
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 29 skipping to change at page 2, line 29
Table of Contents Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3
1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3
1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3
2. Authentication and Authorization . . . . . . . . . . . . . . 3 2. Authentication and Authorization . . . . . . . . . . . . . . 3
3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 6 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 6
3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 8 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 7
3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 8 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 7
3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 7
3.2.2. List/Query Resources . . . . . . . . . . . . . . . . 9 3.2.2. List/Query Resources . . . . . . . . . . . . . . . . 9
3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 16 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 17
3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 18 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 19
3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . 18 3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . 20
3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 20 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 22
3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 27 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 30
3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 28 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 42 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 46
3.7. Additional retrieval query parameters . . . . . . . . . . 42 3.7. Additional retrieval query parameters . . . . . . . . . . 47
3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 43 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 48
3.9. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 43 3.9. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 48
3.10. API Versioning . . . . . . . . . . . . . . . . . . . . . 45 3.10. API Versioning . . . . . . . . . . . . . . . . . . . . . 50
3.11. Versioning Resources . . . . . . . . . . . . . . . . . . 45 3.11. Versioning Resources . . . . . . . . . . . . . . . . . . 50
3.12. HTTP Method Overloading . . . . . . . . . . . . . . . . . 47 3.12. HTTP Method Overloading . . . . . . . . . . . . . . . . . 52
4. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 48 4. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 52
4.1. Associating Consumers to Tenants . . . . . . . . . . . . 49 4.1. Associating Clients to Tenants . . . . . . . . . . . . . 53
4.1.1. URL Prefix Example . . . . . . . . . . . . . . . . . 49 4.1.1. URL Prefix Example . . . . . . . . . . . . . . . . . 54
4.1.2. Subdomain Example . . . . . . . . . . . . . . . . . . 49 4.1.2. Subdomain Example . . . . . . . . . . . . . . . . . . 54
4.1.3. HTTP Header . . . . . . . . . . . . . . . . . . . . . 49 4.1.3. HTTP Header . . . . . . . . . . . . . . . . . . . . . 54
4.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 49 4.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 54
5. Security Considerations . . . . . . . . . . . . . . . . . . . 50 5. Security Considerations . . . . . . . . . . . . . . . . . . . 54
6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 50 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 54
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 50 6.1. Normative References . . . . . . . . . . . . . . . . . . 55
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 50 6.2. Informative References . . . . . . . . . . . . . . . . . 55
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 56
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 56
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 56
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 57
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
This document is intended as a guide to SCIM API usage for both This document is intended as a guide to SCIM API usage for both
identity Service Providers and Consumers. identity service providers and clients.
1.2. Notational Conventions 1.2. Notational Conventions
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 Section 2.1
[1]. [RFC3896].
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 clients 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/v2/
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 authentication can be deployed. Implementers SHOULD support existing authentication
/authorization schemes. In particular, OAuth2 Bearer Token [2] is /authorization schemes. In particular, OAuth2[RFC6750] is
RECOMMENDED. Appropriate security considerations of the selected RECOMMENDED. Appropriate security considerations of the selected
authentication and authorization schemes SHOULD be taken. Because authentication and authorization schemes SHOULD be taken. Because
this protocol uses HTTP response status codes as the primary means of this protocol uses HTTP response status codes as the primary means of
reporting the result of a request, servers are advised to respond to reporting the result of a request, servers are advised to respond to
unauthorized or unauthenticated requests using the 401 response code unauthorized or unauthenticated requests using the 401 response code
in accordance with section 10.4.2 of RFC2616 [3]. in accordance with section 10.4.2 of Section 10.4.2 [RFC2616].
All examples assume OAuth2 bearer token; e.g., All examples assume OAuth2 bearer token [RFC6750]; 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
Resources correspond to /Users and /Groups respectively. Service "Group" resources correspond to "/Users" and "/Groups" respectively.
Providers that support extended Resources SHOULD define Resource Service providers that support extended resources SHOULD define
endpoints using the established convention; pluralize the Resource resource endpoints using the established convention; pluralize the
name defined in the extended schema by appending an 's'. Given there resource name defined in the extended schema by appending an 's'.
are cases where Resource pluralization is ambiguous; e.g., a Resource Given there are cases where resource pluralization is ambiguous;
named 'person' is legitimately 'persons' and 'people' Consumers e.g., a resource named "Person" is legitimately "Persons" and
SHOULD discover Resource endpoints via the Resource Type attribute "People" clients SHOULD discover resource endpoints via the "/
'endpoint'. ResourceTypes" 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, client specified resource
(replace). (replace).
PATCH Modifies a Resource with a set of Consumer specified changes PATCH Modifies a resource with a set of client specified changes
(partial update). (partial update).
DELETE Deletes a Resource. DELETE Deletes a resource.
+------------+--------------------+---------------+-----------------+
| Resource | Endpoint | Operations | Description |
+------------+--------------------+---------------+-----------------+
| User | /Users | GET (Section | Retrieve/Add/Mo |
| | | 3.2.1), POST | dify Users |
| | | (Section | |
| | | 3.1), PUT | |
| | | (Section | |
| | | 3.3.1), PATCH | |
| | | (Section | |
| | | 3.3.2), | |
| | | DELETE | |
| | | (Section 3.4) | |
| Group | /Groups | GET (Section | Retrieve/Add/Mo |
| | | 3.2.1), POST | dify Groups |
| | | (Section | |
| | | 3.1), PUT | |
| | | (Section | |
| | | 3.3.1), PATCH | |
| | | (Section | |
| | | 3.3.2), | |
| | | DELETE | |
| | | (Section 3.4) | |
| Service | /ServiceProviderCo | GET (Section | Retrieve the |
| Provider C | nfigs | 3.2.1) | service |
| onfigurati | | | provider's |
| on | | | configuration |
| Resource | /ResourceTypes | GET (Section | Retrieve the |
| Type | | 3.2.1) | supported |
| | | | resource types |
| Schema | /Schemas | GET (Section | Retrieve a |
| | | 3.2.1) | resource's |
| | | | schema |
| Bulk | /Bulk | POST (Section | Bulk modify |
| | | 3.5) | resources |
| Search | [prefix]/.search | POST (Section | Perform a |
| | | 3.2.3) | search at |
| | | | system root or |
| | | | within a |
| | | | resource |
| | | | endpoint for |
| | | | one or more |
| | | | resource types |
| | | | using POST. |
+------------+--------------------+---------------+-----------------+
+-------------+---------------------+-----------+-------------------+
| Resource | Endpoint | Operation | Description |
| | | s | |
+-------------+---------------------+-----------+-------------------+
| User | /Users | GET | Retrieve/Add/Modi |
| | | (Section | fy Users |
| | | 3.2.1), | |
| | | POST | |
| | | (Section | |
| | | 3.1), PUT | |
| | | (Section | |
| | | 3.3.1), | |
| | | PATCH | |
| | | (Section | |
| | | 3.3.2), | |
| | | DELETE | |
| | | (Section | |
| | | 3.4) | |
| Group | /Groups | GET | Retrieve/Add/Modi |
| | | (Section | fy Groups |
| | | 3.2.1), | |
| | | POST | |
| | | (Section | |
| | | 3.1), PUT | |
| | | (Section | |
| | | 3.3.1), | |
| | | PATCH | |
| | | (Section | |
| | | 3.3.2), | |
| | | DELETE | |
| | | (Section | |
| | | 3.4) | |
| Service | /ServiceProviderCon | GET | Retrieve the |
| Provider Co | figs | (Section | Service |
| nfiguration | | 3.2.1) | Provider's |
| | | | Configuration |
| Resource | /ResourceTypes | GET | Retrieve the |
| Type | | (Section | supported |
| | | 3.2.1) | Resource Types |
| Schema | /Schemas | GET | Retrieve a |
| | | (Section | Resource's Schema |
| | | 3.2.1) | |
| 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 [4] All requests to the service provider are made via Section 9 [RFC2616]
on a URL derived from the Base URL. Responses are returned in the on a URL derived from the Base URL. Responses are returned in the
body of the HTTP response, formatted as JSON. Response and error body of the HTTP response, formatted as JSON. Response and error
codes SHOULD be transmitted via the HTTP status code of the response codes SHOULD be transmitted via the HTTP status code of the response
(if possible), and SHOULD also be specified in the body of the (if possible), and SHOULD also be specified in the body of the
response. 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
can be useful to the client, enabling it to correlate the client and can be useful to the client, enabling it to correlate the client and
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
SHOULD indicate the conflicting attribute(s) in the body of the and 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:2.0:User"], "schemas":["urn:scim:schemas:core:2.0:User"],
"userName":"bjensen", "userName":"bjensen",
skipping to change at page 7, line 21 skipping to change at page 7, line 4
{ {
"schemas":["urn:scim:schemas:core:2.0:User"], "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/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1" ETag: W/"e180ee84f0671b1"
{ {
"schemas":["urn:scim:schemas:core:2.0:User"], "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/v2/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. For example, "/Users" corresponding resource Type for the endpoint. For example, "/Users"
will set "resourceType" to "User", and "/Groups" will set will set "resourceType" to "User", and "/Groups" will set
"resourceType" to "Group". "resourceType" to "Group".
3.2. Retrieving Resources 3.2. Retrieving Resources
Users and Group Resources are retrieved via opaque, unique URLs or "User" 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
To retrieve a known Resource, clients send GET requests to the To retrieve a known resource, clients send GET requests to the
Resource endpoint; e.g., /Users/{id} or /Groups/{id}. resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}".
If the Resource exists the server responds with a status code of 200 If the resource exists the server responds with a status code of 200
and includes the result in the body of the response. and includes the result in the body of the response.
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/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"f250dd84f0671c3" ETag: W/"f250dd84f0671c3"
{
"schemas":["urn:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646,
"externalId":"bjensen",
"meta":{
"resourceType":"User",
"created":"2011-08-01T18:29:49.793Z",
"lastModified":"2011-08-01T18:29:49.793Z",
"location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"f250dd84f0671c3\""
},
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
},
"userName":"bjensen",
"phoneNumbers":[
{
"value":"555-555-8377",
"type":"work"
}
],
"emails":[
{
"value":"bjensen@example.com",
"type":"work"
}
]
}
{
"schemas":["urn:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646",
"externalId":"bjensen",
"meta":{
"resourceType":"User",
"created":"2011-08-01T18:29:49.793Z",
"lastModified":"2011-08-01T18:29:49.793Z",
"location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"f250dd84f0671c3\""
},
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
},
"userName":"bjensen",
"phoneNumbers":[
{
"value":"555-555-8377",
"type":"work"
}
],
"emails":[
{
"value":"bjensen@example.com",
"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: List and query responses MUST be identified using the following URI:
'urn:scim:schemas:core:2.0:ListResponse'. The following attributes "urn:scim:schemas:core:2.0:ListResponse". The following attributes
are defined for list and query responses: are defined for list and query responses:
totalResults The total number of results returned by the list or totalResults The total number of results returned by the list or
query operation. This may not be equal to the number of elements query operation. This may not be equal to the number of elements
in the Resources attribute of the list response if pagination in the resources attribute of the list response if pagination
(Section 3.2.2.4) is requested. REQUIRED. (Section 3.2.2.4) is requested. REQUIRED.
Resources A multi-valued list of complex objects containing the Resources A multi-valued list of complex objects containing the
requested resources. This may be a subset of the full set of requested resources. This may be a subset of the full set of
Resources if pagination (Section 3.2.2.4) is requested. REQUIRED. resources if pagination (Section 3.2.2.4) is requested. REQUIRED.
startIndex The 1-based index of the first result in the current set 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 of list results. REQUIRED if pagination (Section 3.2.2.4) is
requested. requested.
itemsPerPage The number of Resources returned in a list response itemsPerPage The number of resources returned in a list response
page. REQUIRED if pagination (Section 3.2.2.4) is requested. 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"], "schemas":["urn:scim:schemas:core:2.0:ListResponse"],
"totalResults":2, "totalResults":2,
"Resources":[ "Resources":[
{ {
"userName":"bjensen" "userName":"bjensen"
}, },
skipping to change at page 10, line 37 skipping to change at page 10, line 22
"userName":"bjensen" "userName":"bjensen"
}, },
{ {
"userName":"jsmith" "userName":"jsmith"
} }
] ]
} }
3.2.2.1. Query Endpoints 3.2.2.1. Query Endpoints
Queries MAY be performed against a SCIM: Queries MAY be performed against a SCIM resource object or a resource
type endpoint. For example:
Resource (e.g. /Users/{userid}), "/Users/{userid}"
Resource Type endpoint (e.g. /Users or /Groups), or "/Users"
Server Root (e.g. /). "/Groups"
A search against a server root indicates that ALL resources within A server MAY support searches against the server root (e.g. "/"). A
the server SHALL be included subject to filtering. For example, a search against a server root indicates that ALL resources within the
filter against 'meta.resourceType' could be used to restrict results server SHALL be included subject to filtering. A filter expression
to one or more specific resource types. using "meta.resourceType" MAY be used to restrict results to one or
more specific resource types (e.g. "User").
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. Clients may request a subset of resources by
by specifying the 'filter' URL query parameter containing a filter 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
strings [5]. [RFC4627].
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 | | eq | equal | The attribute and operator values must |
| | | must be identical for a match. | | | | be identical for a match. |
| co | contains | The entire operator value must be a | | ne | not equal | The attribute and operator values are |
| | | substring of the attribute value for | | | | not identical. |
| | | a match. | | co | contains | The entire operator value must be a |
| sw | starts with | The entire operator value must be a | | | | substring of the attribute value for a |
| | | substring of the attribute value, | | | | match. |
| | | starting at the beginning of the | | sw | starts with | The entire operator value must be a |
| | | attribute value. This criterion is | | | | substring of the attribute value, |
| | | satisfied if the two strings are | | | | starting at the beginning of the |
| | | identical. | | | | attribute value. This criterion is |
| pr | present (has | If the attribute has a non-empty | | | | satisfied if the two strings are |
| | value) | value, or if it contains a non-empty | | | | identical. |
| | | node for complex attributes there is | | ew | ends with | The entire operator value must be a |
| | | a match. | | | | substring of the attribute value, |
| gt | greater than | If the attribute value is greater | | | | matching at the end of the attribute |
| | | than operator value, there is a | | | | value. This criterion is satisfied if |
| | | match. The actual comparison is | | | | the two strings are identical. |
| | | dependent on the attribute type. For | | pr | present | If the attribute has a non-empty value, |
| | | string attribute types, this is a | | | (has value) | or if it contains a non-empty node for |
| | | lexicographical comparison and for | | | | complex attributes there is a match. |
| | | DateTime types, it is a chronological | | gt | greater | If the attribute value is greater than |
| | | comparison. | | | than | operator value, there is a match. The |
| ge | greater than | If the attribute value is greater | | | | actual comparison is dependent on the |
| | or equal | than or equal to the operator value, | | | | attribute type. For string attribute |
| | | there is a match. The actual | | | | types, this is a lexicographical |
| | | 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 | | ge | greater | If the attribute value is greater than |
| | | comparison and for DateTime types, it | | | than or | or equal to the operator value, there is |
| | | is a chronological comparison. | | | equal | a match. The actual comparison is |
| lt | less than | If the attribute value is less than | | | | dependent on the attribute type. For |
| | | operator value, there is a match. The | | | | string attribute types, this is a |
| | | actual comparison is dependent on the | | | | lexicographical comparison and for |
| | | attribute type. For string attribute | | | | DateTime types, it is a chronological |
| | | types, this is a lexicographical | | | | comparison. |
| | | comparison and for DateTime types, it | | lt | less than | If the attribute value is less than |
| | | is a chronological comparison. | | | | operator value, there is a match. The |
| le | less than or | If the attribute value is less than | | | | actual comparison is dependent on the |
| | equal | or equal to the operator value, there | | | | attribute type. For string attribute |
| | | is a 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 | | le | less than | If the attribute value is less than or |
| | | DateTime types, it is a chronological | | | or equal | equal to the operator value, there is a |
| | | comparison. | | | | match. The actual comparison is |
+-----------+---------------+---------------------------------------+ | | | dependent on the attribute type. For |
| | | string attribute types, this is a |
| | | 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 | | and | Logical And | The filter is only a match if both |
| | | both expressions evaluate to | | | | expressions evaluate to true. |
| | | true. | | or | Logical or | The filter is a match if either |
| or | Logical or | The filter is a match if either | | | | expression evaluates to true. |
| | | expression evaluates to true. | | not | Not | The filter is a match if the expression |
+-------------+-----------------+-----------------------------------+ | | function | evaluates to false. |
+----------+-------------+------------------------------------------+
Table 3: Logical Operators Table 3: Logical Operators
+-------------+---------------+-------------------------------------+ +----------+-------------+------------------------------------------+
| Operator | Description | Behavior | | Operator | Description | Behavior |
+-------------+---------------+-------------------------------------+ +----------+-------------+------------------------------------------+
| () | Precedence | Boolean expressions may be grouped | | () | Precedence | Boolean expressions may be grouped using |
| | grouping | using parentheses to change the | | | grouping | parentheses to change the standard order |
| | | standard order of operations; i.e., | | | | of operations; i.e., evaluate OR logical |
| | | evaluate OR logical operators | | | | operators before logical AND operators. |
| | | before logical AND operators. | | [] | Complex | Service providers MAY support complex |
+-------------+---------------+-------------------------------------+ | | attribute | filters where expressions MUST be |
| | filter | applied to the same value of a parent |
| | grouping | attribute specified immediately before |
| | | the left square bracket ("["). The |
| | | expression within square brackets ("[" |
| | | and "]") MUST be a valid filter |
| | | expression based upon sub-attributes of |
| | | the parent attribute. Nested expressions |
| | | MAY be used. See examples below. |
+----------+-------------+------------------------------------------+
Table 4: Grouping Operators Table 4: Grouping Operators
Filters MUST be evaluated using standard order of operations [6]. Filters MUST be evaluated using standard order of operations
Attribute operators have the highest precedence, followed by the [Order-Operations]. Attribute operators have the highest precedence,
grouping operator (i.e, parentheses), followed by the logical AND followed by the grouping operator (i.e, parentheses), followed by the
operator, followed by the logical OR operator. logical AND 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
example, to filter by userName the parameter value is userName and to example, to filter by userName the parameter value is userName and to
filter by first name, the parameter value is name.givenName. filter by first name, the parameter value is name.givenName.
Providers MAY support additional filter operations if they choose. Providers MAY support additional filter operations if they choose.
Providers MUST decline to filter results if the specified filter Providers MUST decline to filter results if the specified filter
operation is not recognized and return a HTTP 400 error with an operation is not recognized and return a HTTP 400 error with an
appropriate human readable response. For example, if a Consumer appropriate human readable response. For example, if a client
specified an unsupported operator named 'regex' the Service Provider specified an unsupported operator named 'regex' the service provider
should specify an error response description identifying the Consumer should specify an error response description identifying the client
error; e.g., 'The operator 'regex' is not supported.' error; e.g., 'The operator 'regex' is not supported.'
String type attributes are case insensitive by default unless the String type attributes are case insensitive by default unless the
attribute type is defined as a caseExact string. Attribute operators attribute type is defined as a caseExact string. Attribute operators
'eq', 'co', and 'sw' MUST perform caseIgnore matching for all string 'eq', 'co', and 'sw' MUST perform caseIgnore matching for all string
attributes unless the attribute is defined as caseExact. By default attributes unless the attribute is defined as caseExact. By default
all string attributes are caseIgnore. all string attributes are caseIgnore.
Examples: Clients MAY search by schema or schema extensions by using a filter
expression including the "schemas" attribute.
The following are examples of valid filters. Some attributes (e.g.
rooms and rooms.number) are hypothetical extensions and are not part
of SCIM core schema:
filter=userName eq "bjensen" filter=userName eq "bjensen"
filter=name.familyName co "O'Malley" filter=name.familyName co "O'Malley"
filter=userName sw "J" filter=userName sw "J"
filter=title pr filter=title pr
filter=meta.lastModified gt "2011-05-13T04:42:34Z" filter=meta.lastModified gt "2011-05-13T04:42:34Z"
skipping to change at page 14, line 25 skipping to change at page 14, line 32
filter=meta.lastModified ge "2011-05-13T04:42:34Z" filter=meta.lastModified ge "2011-05-13T04:42:34Z"
filter=meta.lastModified lt "2011-05-13T04:42:34Z" filter=meta.lastModified lt "2011-05-13T04:42:34Z"
filter=meta.lastModified le "2011-05-13T04:42:34Z" filter=meta.lastModified le "2011-05-13T04:42:34Z"
filter=title pr and userType eq "Employee" filter=title pr and userType eq "Employee"
filter=title pr or userType eq "Intern" filter=title pr or userType eq "Intern"
filter=schemas eq "urn:scim:schemas:extension:enterprise:2.0:User"
filter=userType eq "Employee" and (emails co "example.com" or emails filter=userType eq "Employee" and (emails co "example.com" or emails
co "example.org") co "example.org")
filter=userType ne "Employee" and not (emails co "example.com" or
emails co "example.org")
filter=userType eq "Employee" and (emails.type eq "work")
filter=userType eq "Employee" and emails[type eq "work" and
value co "@example.com"]
filter=emails[type eq "work" and value co "@example.com"] or ims[type
eq "xmpp" and value co "@foo.com"]
filter=addresses[state eq "CA" and rooms[type eq "bedroom" and
number gt 2]]
3.2.2.3. Sorting 3.2.2.3. Sorting
Sort is OPTIONAL. Sorting allows Consumers to specify the order in Sort is OPTIONAL. Sorting allows clients to specify the order in
which Resources are returned by specifying a combination of sortBy which resources are returned by specifying a combination of sortBy
and sortOrder URL parameters. and sortOrder URL parameters.
sortBy: The sortBy parameter specifies the attribute whose value sortBy: The sortBy parameter specifies the attribute whose value
SHALL be used to order the returned responses. If the sortBy SHALL be used to order the returned responses. If the sortBy
attribute corresponds to a Singular Attribute, Resources are attribute corresponds to a singular attribute, resources are
sorted according to that attribute's value; if it's a Multi-valued sorted according to that attribute's value; if it's a multi-valued
Attribute, Resources are sorted by the value of the primary attribute, resources are sorted by the value of the primary
attribute, if any, or else the first value in the list, if any. attribute, if any, or else the first value in the list, if any.
If the attribute is complex the attribute name must be a path to a If the attribute is complex the attribute name must be a path to a
Sub-Attribute in standard attribute notation (Section 3.8) ; e.g., sub-attribute in standard attribute notation (Section 3.8) ; e.g.,
sortBy=name.givenName. For all attribute types, if there is no "sortBy=name.givenName". For all attribute types, if there is no
data for the specified sortBy value they are sorted via the data for the specified "sortBy" value they are sorted via the
'sortOrder' parameter; i.e., they are ordered last if ascending "sortOrder" parameter; i.e., they are ordered last if ascending
and first if descending. and first if descending.
sortOrder: The order in which the sortBy parameter is applied. sortOrder: The order in which the sortBy parameter is applied.
Allowed values are "ascending" and "descending". If a value for Allowed values are "ascending" and "descending". If a value for
sortBy is provided and no sortOrder is specified, the sortOrder sortBy is provided and no sortOrder is specified, the sortOrder
SHALL default to ascending. String type attributes are case SHALL default to ascending. String type attributes are case
insensitive by default unless the attribute type is defined as a insensitive by default unless the attribute type is defined as a
caseExact string. sortOrder MUST sort according to the attribute case exact string. "sortOrder" MUST sort according to the
type; i.e., for caseIgnore attributes, sort the result using case attribute type; i.e., for "caseIgnore" attributes, sort the result
insensitive, Unicode alphabetic sort order, with no specific using case insensitive, unicode alphabetic sort order, with no
locale implied and for caseExact attribute types, sort the result specific locale implied and for caseExact attribute types, sort
using case sensitive, Unicode alphabetic sort order. the result using case sensitive, Unicode alphabetic sort order.
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 client or service
Provider. Pagination is not session based hence Consumers SHOULD provider. Pagination is not session based hence clients SHOULD never
never assume repeatable results. For example, a request for a list assume repeatable results. For example, a request for a list of 10
of 10 Resources beginning with a startIndex of 1 may return different 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 [7]. Protocol [OpenSearch].
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 of | 1 | | startIndex | The 1-based index | 1 |
| | the first search | | | | of the first | |
| | result. | | | | search result. | |
| count | Non-negative | None. When specified the | | count | Non-negative | None. When specified the service |
| | Integer. Specifies | Service Provider MUST not | | | Integer. | provider MUST not return more |
| | the desired maximum | return more results than | | | Specifies the | results than specified though |
| | number of search | specified though MAY return | | | desired maximum | MAY return fewer results. If |
| | results per page; | fewer results. If | | | number of search | unspecified, the maximum number |
| | e.g., 10. | unspecified, the maximum | | | results per page; | of results is set by the service |
| | | number of results is set by | | | e.g., 10. | provider. |
| | | 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 | | | search results returned in a query response page; |
| | page; e.g., 10. | | | e.g., 10. |
| totalResults | Non-negative Integer. Specifies the total | | totalResults | Non-negative Integer. Specifies the total number |
| | number of results matching the Consumer query; | | | of results matching the client query; e.g., 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
skipping to change at page 17, line 6 skipping to change at page 17, line 35
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: Search requests MUST be identified using the following URI:
'urn:scim:schemas:core:2.0:SearchRequest'. The following attributes 'urn:scim:schemas:core:2.0:SearchRequest'. The following attributes
are defined for search requests: are defined for search requests:
attributes A multi-valued list of strings indicating the names of attributes A multi-valued list of strings indicating the names of
Resource attributes to return in the response. Attribute names resource attributes to return in the response. Attribute names
MUST be in standard attribute notation (Section 3.8) form. See MUST be in standard attribute notation (Section 3.8) form. See
additional retrieval query parameters (Section 3.7). OPTIONAL. additional retrieval query parameters (Section 3.7). OPTIONAL.
filter The filter string used to request a subset of Resources. The 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. filter string MUST be a valid filter (Section 3.2.2.2) expression.
OPTIONAL. OPTIONAL.
sortBy A string indicating the attribute whose value SHALL be used sortBy A string indicating the attribute whose value SHALL be used
to order the returned responses. The sortBy attribute MUST be in to order the returned responses. The sortBy attribute MUST be in
standard attribute notation (Section 3.8) form. See sorting standard attribute notation (Section 3.8) form. See sorting
(Section 3.2.2.3). OPTIONAL. (Section 3.2.2.3). OPTIONAL.
sortOrder A string indicating the order in which the sortBy sortOrder A string indicating the order in which the sortBy
parameter is applied. Allowed values are "ascending" and parameter is applied. Allowed values are "ascending" and
skipping to change at page 17, line 35 skipping to change at page 18, line 17
count An integer indicating the desired maximum number of search count An integer indicating the desired maximum number of search
results per page. See pagination (Section 3.2.2.4). OPTIONAL. 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.
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 POST /.search
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:2.0:SearchRequest"], "schemas": ["urn:scim:schemas:core:2.0:SearchRequest"],
"attributes": ["displayName", "username"], "attributes": ["displayName", "userName"],
"filter": "displayName sw \"smith\"", "filter": "displayName sw \"smith\"",
"startIndex": 1, "startIndex": 1,
"count": 10 "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 HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Location: https://example.com/.search Location: https://example.com/.search
{ {
"schemas": ["urn:scim:schemas:core:2.0:ListResponse"], "schemas": ["urn:scim:schemas:core:2.0:ListResponse"],
"totalResults":100, "totalResults":100,
"itemsPerPage":10, "itemsPerPage":10,
"startIndex":1, "startIndex":1,
"Resources":[ "Resources":[
{ {
"meta":{ "meta":{
"location": "location":
"https://example.com/Users/2819c223-7f76-413861904646", "https://example.com/Users/2819c223-7f76-413861904646",
"resourceType":"User", "resourceType":"User",
"lastModified": ... "lastModified": ...
} },
"username":"jsmith", "userName":"jsmith",
"displayName":"Smith, James" "displayName":"Smith, James"
}, },
{ {
"meta":{ "meta":{
"location": "location":
"https://example.com/Groups/c8596b90-7539-4f20968d1908", "https://example.com/Groups/c8596b90-7539-4f20968d1908",
"resourceType":"Group", "resourceType":"Group",
"lastModified": ... "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
[8] . Resources such as Groups may be very large hence implementers Section 9.6 [RFC2616] . Resources such as Groups may be very large
SHOULD support PATCH [9] to enable partial resource modifications. hence implementers SHOULD support PATCH [RFC5789] 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. Clients MAY retrieve the entire resource
Resource and PUT the desired modifications as the operation in advance, add the desired modifications and use HTTP PUT which will
overwrites all previously stored data with the exception of the overwrite all previously stored data. Since the PUT request performs
password attribute. If the password attribute of the User resource a full update, clients MAY send attributes of the retrieved resource
is unspecified, it should be left in-tact. Since this performs a and the service provider MUST process according to attribute
full update, Consumers MAY send read-only attributes of the retrieved mutability as follows:
resource and the Service Provider MUST ignore any read-only
attributes that are present in the payload of a PUT request. Unless readWrite, writeOnly Any values provided SHALL replace the existing
otherwise specified a successful PUT operation returns a 200 OK attribute values. Omitting the attribute or specific values means
response code and the entire Resource within the response body, the attribute or specific value SHALL be removed;
enabling the Consumer to correlate the Consumer's and Provider's
views of the updated Resource. Example: immutable If values are provided for elements already set in the
attribute they MUST match existing data or an error is returned.
If the service provider has no existing values, a new value(s) MAY
be specified; and,
readOnly Any values provided (e.g. meta.resourceType) SHALL be
ignored.
If an attribute is "required", the client MUST specify the attribute
in the PUT request.
If a value provided for an immutable attribute with an existing value
is NOT matched, the server SHALL respond with an HTTP response code
of 400 and an apprpriate human readable message indicating an attempt
to change an immutable attribute.
Unless otherwise specified a successful PUT operation returns a 200
OK response code and the entire resource within the response body,
enabling the client to correlate the client's and Provider's 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:2.0:User"], "schemas":["urn:scim:schemas:core:2.0:User"],
skipping to change at page 19, line 45 skipping to change at page 22, line 5
"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/v2/Users/2819c223-7f76-453a-919d-413861904646"
{ {
"schemas":["urn:scim:schemas:core:2.0:User"], "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/v2/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 clients 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
response code and the entire Resource (subject to the "attributes" response code and the entire resource (subject to the "attributes"
query parameter - see Additional Retrieval Query Parameters query parameter - see Additional Retrieval Query Parameters
(Section 3.7)) within the response body, or a 204 No Content response (Section 3.7)) within the response body, or a 204 No Content response
code and the appropriate response headers for a successful PATCH code and the appropriate response headers for a successful PATCH
request. The server MUST return a 200 OK if the "attributes" request. The server MUST return a 200 OK if the "attributes"
parameter is specified on the request. parameter is specified on the request.
The server MUST process a PATCH request by first removing any The server MUST process a PATCH request by first removing any
attributes specified in the meta.attributes Sub-Attribute (if attributes specified in the meta.attributes Sub-Attribute (if
present) and then merging the attributes in the PATCH request body present) and then merging the attributes in the PATCH request body
into the Resource. into the resource.
The meta.attributes Sub-Attribute MAY contain a list of attributes to The meta.attributes Sub-Attribute MAY contain a list of attributes to
be removed from the Resource. If the PATCH request body contains an be removed from the resource. If the PATCH request body contains an
attribute that is present in the meta.attributes list, the attribute attribute that is present in the meta.attributes list, the attribute
on the Resource is replaced with the value from the PATCH body. If on the resource is replaced with the value from the PATCH body. If
the attribute is complex the attribute name must be a path to a Sub- the attribute is complex the attribute name must be a path to a Sub-
Attribute in standard attribute notation (Section 3.8); e.g., Attribute in standard attribute notation (Section 3.8); e.g.,
name.givenName. name.givenName.
Attributes that exist in the PATCH request body but not in the Attributes that exist in the PATCH request body but not in the
meta.attributes Sub-Attribute will be either be updated or added to meta.attributes Sub-Attribute will be either be updated or added to
the Resource according to the following rules. the resource according to the following rules.
Singular attributes: Singular attributes in the PATCH request body Singular attributes: Singular attributes in the PATCH request body
replace the attribute on the Resource. replace the attribute on the resource.
Complex attributes: Complex Sub-Attribute values in the PATCH Complex attributes: Complex Sub-Attribute values in the PATCH
request body are merged into the complex attribute on the request body are merged into the complex attribute on the
Resource. resource.
Multi-valued attributes: An attribute value in the PATCH request Multi-valued attributes: An attribute value in the PATCH request
body is added to the value collection if the value does not exist body is added to the value collection if the value does not exist
and merged if a matching value is present. Values are matched by and merged if a matching value is present. Values are matched by
comparing the value Sub-Attribute from the PATCH request body to comparing the value Sub-Attribute from the PATCH request body to
the value Sub-Attribute of the Resource. Attributes that do not the value Sub-Attribute of the resource. Attributes that do not
have a value Sub-Attribute; e.g., addresses, or do not have unique have a value Sub-Attribute; e.g., addresses, or do not have unique
value Sub-Attributes cannot be matched and must instead be deleted value Sub-Attributes cannot be matched and must instead be deleted
then added. Specific values can be removed from a Resource by then added. Specific values can be removed from a resource by
adding an "operation" Sub-Attribute with the value "delete" to the adding an "operation" Sub-Attribute with the value "delete" to the
attribute in the PATCH request body. As with adding/updating attribute in the PATCH request body. As with adding/updating
attribute value collections, the value to delete is determined by attribute value collections, the value to delete is determined by
comparing the value Sub-Attribute from the PATCH request body to comparing the value Sub-Attribute from the PATCH request body to
the value Sub-Attribute of the Resource. Attributes that do not the value Sub-Attribute of the resource. Attributes that do not
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:2.0:Group"], "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/v2/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/v2/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:2.0:Group"], "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/v2/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"
skipping to change at page 23, line 32 skipping to change at page 26, line 5
"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:2.0:Group"], "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/v2/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/v2/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:2.0:Group"], "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/v2/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/v2/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
skipping to change at page 25, line 17 skipping to change at page 28, line 4
{ {
"schemas": ["urn:scim:schemas:core:2.0:User"], "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:2.0:User"], "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"
skipping to change at page 26, line 43 skipping to change at page 29, line 37
"schemas": ["urn:scim:schemas:core:2.0:User"], "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"
{ {
skipping to change at page 27, line 38 skipping to change at page 30, line 42
"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
Consumers request Resource removal via DELETE. Service Providers MAY Clients request resource removal via DELETE. Service providers MAY
choose not to permanently delete the Resource, but MUST return a 404 choose not to permanently delete the resource, but MUST return a 404
error code for all operations associated with the previously deleted error code for all operations associated with the previously deleted
Id. Service Providers MUST also omit the Resource from future query Id. Service providers MUST also omit the resource from future query
results. In addition the Service Provider MUST not consider the results. In addition the service provider MUST not consider the
deleted resource in conflict calculation. For example if a User deleted resource in conflict calculation. For example if a User
resource is deleted, a CREATE request for a User resource with the resource is deleted, a CREATE request for a User resource with the
same userName as the previously deleted resource should not fail with same userName as the previously deleted resource should not fail with
a 409 error due to userName conflict. a 409 error due to userName conflict.
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: In response to a successful delete, the server SHALL respond with
successful HTTP status 204 (No Content). A non-normative example
response:
HTTP/1.1 200 OK HTTP/1.1 204 No Content
Example: Consumer attempt to retrieve the previously deleted User Example: client 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
{ {
"schemas": ["urn:scim:schemas:core:2.0:Error"], "schemas": ["urn:scim:schemas:core:2.0:Error"],
"Errors":[ "Errors":[
{ {
"description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
"code":"404" "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 clients 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: Bulk requests are identified using the following URI:
'urn:scim:schemas:core:2.0:BulkRequest'. Bulk responses are 'urn:scim:schemas:core:2.0:BulkRequest'. Bulk responses are
identified using the following URI: identified using the following URI:
'urn:scim:schemas:core:2.0:BulkResponse'. Bulk requests and bulk 'urn:scim:schemas:core:2.0:BulkResponse'. Bulk requests and bulk
responses share many attributes. Unless otherwise specified, each responses share many attributes. Unless otherwise specified, each
attribute below is present in both bulk requests and bulk responses. 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 in a request. Not and an error response is returned. OPTIONAL in a request. Not
valid in a response. 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. unique within a bulk request and created by the client. The
The bulkId serves as a surrogate Resource id enabling bulkId serves as a surrogate resource id enabling clients to
Consumers to uniquely identify newly created Resources in uniquely identify newly created resources in the Response and
the Response and cross reference new Resources in and across cross reference new resources in and across operations within a
operations within a bulk request. REQUIRED when method is bulk request. REQUIRED when method is POST.
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, service provider supports ETags and the method is PUT, DELETE,
DELETE, or PATCH. 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 Groups whereas all other method values must specify the path to
path to a specific Resource; e.g., /Users/2819c223-7f76 a specific resource; e.g., /Users/2819c223-7f76-453a-
-453a-919d-413861904646. REQUIRED in a request. 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 or PATCH resource operation. REQUIRED in a request when method
method is POST, PUT and PATCH. 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 or failure of one operation within the bulk job. REQUIRED in a
in a response. response.
code The HTTP response code that would have been code The HTTP response code that would have been returned if a
returned if a a single HTTP request would have been a single HTTP request would have been used. REQUIRED.
used. REQUIRED.
description A human readable error message. REQUIRED when description A human readable error message. REQUIRED when an
an error occurred. 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 client 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
returning the response. returning the response.
To be able to reference a newly created Resource the attribute bulkId To be able to reference a newly created resource the attribute bulkId
MUST be specified when creating new Resources. The bulkId is defined MUST be specified when creating new resources. The bulkId is defined
by the Consumer as a surrogate identifier in a POST operation. The by the client as a surrogate identifier in a POST operation. The
Service Provider MUST return the same bulkId together with the newly service provider MUST return the same bulkId together with the newly
created Resource. The bulkId can then be used by the Consumer to map created resource. The bulkId can then be used by the client to map
the Service Provider id with the bulkId of the created Resource. the service provider id with the bulkId of the created resource.
There can be more then one operation per Resource in each bulk job. There can be more then one operation per resource in each bulk job.
The Service Consumer MUST take notice of the unordered structure of The Service client MUST take notice of the unordered structure of
JSON and the Service Provider can process operations in any order. JSON and the service provider can process operations in any order.
For example, if the Service Consumer sends two PUT operations in one For example, if the Service client sends two PUT operations in one
request, the outcome is non-deterministic. request, the outcome is non-deterministic.
The Service Provider response MUST include the result of all The service provider response MUST include the result of all
processed operations. A location attribute that includes the processed operations. A location attribute that includes the
Resource's end point MUST be returned for all operations excluding resource's end point MUST be returned for all operations excluding
failed POSTs. The status attribute includes information about the failed POSTs. The status attribute includes information about the
success or failure of one operation within the bulk job. The success or failure of one operation within the bulk job. The
attribute status MUST include the code attribute that holds the HTTP attribute status MUST include the code attribute that holds the HTTP
response code that would have been returned if a single HTTP request response code that would have been returned if a single HTTP request
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 client to match the new
new User with the returned Resource id '92b725cd-9465-4e7d- User with the returned resource id '92b725cd-9465-4e7d-
8c16-01f8e146b87a'. 8c16-01f8e146b87a'.
POST /v1/Bulk POST /v2/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": ["urn:scim:schemas:core:2.0:BulkRequest"], "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"],
"failOnErrors":1, "failOnErrors":1,
"Operations":[ "Operations":[
skipping to change at page 32, line 31 skipping to change at page 35, line 30
} }
}, },
{ {
"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"], "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"],
"Operations": [ "Operations": [
{ {
"location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST", "method": "POST",
"bulkId": "qwerty", "bulkId": "qwerty",
"version": "W\/\"oY4m4wn58tkVjJxK\"", "version": "W\/\"oY4m4wn58tkVjJxK\"",
"status": { "status": {
"code": "201" "code": "201"
} }
}, },
{ {
"location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041", "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT", "method": "PUT",
"version": "W\/\"huJj29dMNgu3WXPD\"", "version": "W\/\"huJj29dMNgu3WXPD\"",
"status": { "status": {
"code": "200" "code": "200"
} }
}, },
{ {
"location": "https://example.com/v1/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH", "method": "PATCH",
"version": "W\/\"huJj29dMNgu3WXPD\"", "version": "W\/\"huJj29dMNgu3WXPD\"",
"status": { "status": {
"code": "200" "code": "200"
} }
}, },
{ {
"location": "https://example.com/v1/Users/e9025315-6bea-44e1-899c-1e07454e468b", "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE", "method": "DELETE",
"status": { "status": {
"code": "200" "code": "204"
} }
} }
] ]
} }
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 client. 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": ["urn:scim:schemas:core:2.0:BulkResponse"], "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"bulkId": "qwerty", "bulkId": "qwerty",
"status": { "status": {
"code": "400", "code": "400",
"description": "Request is unparseable, syntactically incorrect, or violates schema." "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 client 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": ["urn:scim:schemas:core:2.0:BulkResponse"], "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"bulkId": "qwerty", "bulkId": "qwerty",
"status": { "status": {
"code": "400", "code": "400",
"description": "Request is unparseable, syntactically incorrect, or violates schema." "description": "Request is unparseable, syntactically incorrect, or violates schema."
} }
}, },
{ {
"location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041", "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT", "method": "PUT",
"status": { "status": {
"code": "412", "code": "412",
"description": "Failed to update as user changed on the server since you last retrieved it." "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", "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH", "method": "PATCH",
"status": { "status": {
"code": "412", "code": "412",
"description": "Failed to update as user changed on the server since you last retrieved it." "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", "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE", "method": "DELETE",
"status": { "status": {
"code": "404", "code": "404",
"description": "Specified resource; e.g., User, does not exist." "description": "Specified resource; e.g., User, does not exist."
} }
} }
] ]
} }
The Consumer can, within one bulk operation, create a new User, a new The client 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 client 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.
The following example creates a User with the userName 'Alice' and a The following example creates a User with the userName 'Alice' and a
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 /v2/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": ["urn:scim:schemas:core:2.0:BulkRequest"], "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"],
"Operations": [ "Operations": [
{ {
skipping to change at page 36, line 25 skipping to change at page 39, line 47
{ {
"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
Content-Type: application/json
{ HTTP/1.1 200 OK
"schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], Content-Type: application/json
"Operations": [
{
"location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST",
"bulkId": "qwerty",
"version": "W\/\"4weymrEsh5O6cAEK\"",
"status": {
"code": "201"
}
},
{
"location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"method": "POST",
"bulkId": "ytrewq",
"version": "W\/\"lha5bbazU3fNvfe5\"",
"status": {
"code": "201"
}
}
] {
} "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"],
"Operations": [
{
"location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST",
"bulkId": "qwerty",
"version": "W\/\"4weymrEsh5O6cAEK\"",
"status": {
"code": "201"
}
},
{
"location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"method": "POST",
"bulkId": "ytrewq",
"version": "W\/\"lha5bbazU3fNvfe5\"",
"status": {
"code": "201"
}
}
]
}
A subsequent request for the 'Tour Guides' Group ('e9e30dba- A subsequent request for the 'Tour Guides' Group ('e9e30dba-
f08f-4109-8486-d5c6a331660a') returns the following: f08f-4109-8486-d5c6a331660a') returns the following:
GET /v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a GET /v2/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/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
ETag: W/"lha5bbazU3fNvfe5" ETag: W/"lha5bbazU3fNvfe5"
{ {
"schemas": ["urn:scim:schemas:core:2.0:Group"], "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": {
"resourceType": "Group", "resourceType": "Group",
"created": "2011-08-01T18:29:49.793Z", "created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T20:31:02.315Z", "lastModified": "2011-08-01T20:31:02.315Z",
"location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"version": "W\/\"lha5bbazU3fNvfe5\"" "version": "W\/\"lha5bbazU3fNvfe5\""
}, },
"members": [ "members": [
{ {
"value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a",
"$ref": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", "$ref": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"type": "User" "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 /v2/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": ["urn:scim:schemas:core:2.0:BulkRequest"], "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"],
"Operations": [ "Operations": [
{ {
skipping to change at page 38, line 44 skipping to change at page 42, line 46
"manager": { "manager": {
"managerId": "batchId:qwerty", "managerId": "batchId:qwerty",
"displayName": "Alice" "displayName": "Alice"
} }
} }
} }
} }
] ]
} }
The Service Provider MUST try to resolve circular cross references The service provider MUST try to resolve circular cross references
between Resources in a single bulk job but MAY stop after a failed between resources in a single bulk job but MAY stop after a failed
attempt and instead return the status code 409 Conflict. The attempt and instead return the status code 409 Conflict. The
following example exhibits the potential conflict. following example exhibits the potential conflict.
POST /v1/Bulk POST /v2/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": ["urn:scim:schemas:core:2.0:BulkRequest"], "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"],
"Operations": [ "Operations": [
{ {
skipping to change at page 39, line 46 skipping to change at page 43, line 48
{ {
"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 /v2/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
{
"schemas": ["urn:scim:schemas:core:2.0:ListResponse"],
"totalResults": 2,
"Resources": [
{
"id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"schemas": ["urn:scim:schemas:core:2.0:Group"],
"displayName": "Group A",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T18:29:51.135Z",
"location": "https://example.com/v1/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"version": "W\/\"mvwNGaxB5SDq074p\""
},
"members": [
{
"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",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:50.873Z",
"lastModified": "2011-08-01T18:29:50.873Z",
"location": "https://example.com/v1/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"version": "W\/\"wGB85s2QJMjiNnuI\""
},
"members": [
{
"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 {
maximum payload size a Consumer may send in a single request. If "schemas": ["urn:scim:schemas:core:2.0:ListResponse"],
either limits are exceeded the Service Provider MUST return the HTTP "totalResults": 2,
"Resources": [
{
"id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"schemas": ["urn:scim:schemas:core:2.0:Group"],
"displayName": "Group A",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T18:29:51.135Z",
"location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"version": "W\/\"mvwNGaxB5SDq074p\""
},
"members": [
{
"value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"$ref": "https://example.com/v2/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",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:50.873Z",
"lastModified": "2011-08-01T18:29:50.873Z",
"location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"version": "W\/\"wGB85s2QJMjiNnuI\""
},
"members": [
{
"value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"type": "Group"
}
]
}
]
}
The service provider MUST define the maximum number of operations and
maximum payload size a client may send in a single request. If
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 client sent a request exceeding the service
Service Provider's max payload size of 1 megabyte. provider's max payload size of 1 megabyte.
POST /v1/Bulk POST /v2/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/v2/Bulk/yfCrVJhFIJagAHj8
{ {
"schemas":["urn:scim:schemas:core:2.0:Error"], "schemas":["urn:scim:schemas:core:2.0:Error"],
"Errors":[ "Errors":[
{ {
"description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).", "description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).",
"code":"413" "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 Clients MUST specify the format in which the data is submitted via
the HTTP header content-type [10] and MAY specify the desired the Section 14.17 HTTP header content-type [RFC2616] and MAY specify
response data format via an HTTP Accept Header; e.g.,"Accept: the desired response data format via an HTTP Accept Header;
application/json" or via URI suffix; e.g., e.g.,"Accept: 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 [11]. The format defaults to JSON if no application/json" for [RFC4627]. 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" ]
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 Clients 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 MUST returned MUST contain the minimal set of resource attributes and MUST
contain no other attributes or Sub-Attributes than those explicitly contain no other attributes or Sub-Attributes than those explicitly
requested. The query parameter attributes value is a comma separated requested. The query parameter attributes value is a comma separated
list of Resource attribute names in standard attribute notation list of resource attribute names in standard 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/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"a330bc54f0671c9" ETag: W/"a330bc54f0671c9"
{ {
"schemas":["urn:scim:schemas:core:2.0:User"], "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":{
"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/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"a330bc54f0671c9\"" "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:2.0:userName'. Consumers MAY identified as 'urn:scim:schemas:core:2.0:User:userName'. Clients 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
for a User's givenName is urn:scim:schemas:core:2.0:name.givenName a User's givenName is urn:scim:schemas:core:2.0:User: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 [12] The SCIM Protocol uses the response status codes defined in HTTP
to indicate operation success or failure. In addition to returning a Section 10 [RFC2616] to indicate operation success or failure. In
HTTP response code implementers MUST return the errors in the body of addition to returning a HTTP response code implementers MUST return
the response in the client requested format containing the error the errors in the body of the response in the client requested format
response and, per the HTTP specification, human-readable containing the error response and, per the HTTP specification, human-
explanations. Error responses are identified using the following readable explanations. Error responses are identified using the
URI: 'urn:scim:schemas:core:2.0:Error'. The following multi-valued following URI: 'urn:scim:schemas:core:2.0:Error'. The following
attribute is defined in addition to those attributes defined in SCIM multi-valued attribute is defined in addition to those attributes
Core Schema: defined in SCIM Core Schema:
Errors The list of errors encountered by the Service Provider. The Errors The list of errors encountered by the service provider. The
value attribute is a complex type with the following sub- value attribute is a complex type with the following sub-
attributes. attributes.
description A human-readable explanation of the error. REQUIRED. description A human-readable explanation of the error. REQUIRED.
code A string indicating the HTTP response code. REQUIRED. code A string indicating the HTTP response code. REQUIRED.
Implementers SHOULD handle the identified errors as described below. Implementers SHOULD handle the identified errors as described below.
+----------------+---------------------------+----------------------+ +--------------+---------------+------------------------------------+
| Code | Applicability | Suggested | | Code | Applicability | Suggested Explanation |
| | | Explanation | +--------------+---------------+------------------------------------+
+----------------+---------------------------+----------------------+ | 307 | GET, POST, | The client is directed to repeat |
| 400 BAD | GET,POST,PUT,PATCH,DELETE | Request is | | TEMPORARY | PUT, PATCH, | the same HTTP request at the |
| REQUEST | | unparseable, | | REDIRECT | DELETE | location identified. The client |
| | | syntactically | | | | SHOULD NOT use the location |
| | | incorrect, or | | | | provided in the response as a |
| | | violates schema | | | | permanent reference to the |
| 401 | GET,POST,PUT,PATCH,DELETE | Authorization | | | | resource and SHOULD continue to |
| UNAUTHORIZED | | failure | | | | use the original request URI |
| 403 FORBIDDEN | GET,POST,PUT,PATCH,DELETE | Server does not | | | | [I-D.ietf-httpbis-p2-semantics]. |
| | | support requested | | 308 | GET, POST, | The client is directed to repeat |
| | | operation | | PERMANENT | PUT, PATCH, | the same HTTP request at the |
| 404 NOT FOUND | GET,PUT,PATCH,DELETE | Specified resource; | | REDIRECT | DELETE | location identified. The client |
| | | e.g., User, does not | | | | SHOULD use the location provided |
| | | exist | | | | in the response as the permanent |
| 409 CONFLICT | POST, PUT,PATCH,DELETE | The specified | | | | reference to the resource |
| | | version number does | | | | [I-D.reschke-http-status-308]. |
| | | not match the | | 400 BAD | GET, POST, | Request is unparseable, |
| | | resource's latest | | REQUEST | PUT, PATCH, | syntactically incorrect, or |
| | | version number or a | | | DELETE | violates schema |
| | | Service Provider | | 401 | GET, POST, | Authorization failure |
| | | refused to create a | | UNAUTHORIZED | PUT, PATCH, | |
| | | new, duplicate | | | DELETE | |
| | | resource | | 403 | GET, POST, | Server does not support requested |
| 412 | PUT,PATCH,DELETE | Failed to update as | | FORBIDDEN | PUT, PATCH, | operation |
| PRECONDITION | | Resource {id} | | | DELETE | |
| FAILED | | changed on the | | 404 NOT | GET, PUT, | Specified resource; e.g., User, |
| | | server last | | FOUND | PATCH, DELETE | does not exist |
| | | retrieved | | 409 CONFLICT | POST, PUT, | The specified version number does |
| 413 REQUEST | POST | {"maxOperations": | | | PATCH, DELETE | not match the resource's latest |
| ENTITY TOO | | 1000,"maxPayload": | | | | version number or a service |
| LARGE | | 1048576} | | | | provider refused to create a new, |
| 500 INTERNAL | GET,POST,PUT,PATCH,DELETE | An internal error. | | | | duplicate resource |
| SERVER ERROR | | Implementers SHOULD | | 412 | PUT, PATCH,D | Failed to update as resource {id} |
| | | provide descriptive | | PRECONDITION | ELETE | changed on the server last |
| | | debugging advice | | FAILED | | retrieved |
| 501 NOT | GET,POST,PUT,PATCH,DELETE | Service Provider | | 413 REQUEST | POST | {"maxOperations": |
| IMPLEMENTED | | does not support the | | ENTITY TOO | | 1000,"maxPayload": 1048576} |
| | | request operation; | | LARGE | | |
| | | e.g., PATCH | | 500 INTERNAL | GET, POST, | An internal error. Implementers |
+----------------+---------------------------+----------------------+ | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive |
| | DELETE | debugging advice |
| 501 NOT | GET, POST, | Service Provider does not support |
| IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH |
| | DELETE | |
+--------------+---------------+------------------------------------+
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
{ {
"schemas": ["urn:scim:schemas:core:2.0:Error"], "schemas": ["urn:scim:schemas:core:2.0:Error"],
"Errors":[ "Errors":[
{ {
"description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
"code":"404" "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 /v1 version number; e.g., a version 'v1' User request is specified as /v2
/Users. When specified Service Providers MUST perform the operation /Users. When specified service providers MUST perform the operation
using the desired version or reject the request. When omitted using the desired version or reject the request. When omitted
Service Providers SHOULD perform the operation using the most recent service providers SHOULD perform the operation using the most 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 [13]. The API supports resource versioning via standard HTTP
Service providers MAY support weak ETags as the preferred mechanism ETagsSection 14.19 [RFC2616]. Service providers MAY support weak
for performing conditional retrievals and ensuring Consumers do not ETags as the preferred mechanism for performing conditional
inadvertently overwrite each others changes, respectively. When retrievals and ensuring clients do not inadvertently overwrite each
supported SCIM ETags MUST be specified as an HTTP header and SHOULD others changes, respectively. When supported SCIM ETags MUST be
be specified within the 'version' attribute contained in the specified as an HTTP header and SHOULD be specified within the
Resource's 'meta' attribute. 'version' attribute contained in the 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: ...
{ {
skipping to change at page 47, line 5 skipping to change at page 51, line 29
"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/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1" ETag: W/"e180ee84f0671b1"
{
"schemas":["urn:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646",
"meta":{
"resourceType":"User",
"created":"2011-08-01T21:32:44.882Z",
"lastModified":"2011-08-01T21:32:44.882Z",
"location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"e180ee84f0671b1\""
},
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
},
"userName":"bjensen"
}
With the returned ETag, Consumers MAY choose to retrieve the Resource {
only if the Resource has been modified. "schemas":["urn:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646",
"meta":{
"resourceType":"User",
"created":"2011-08-01T21:32:44.882Z",
"lastModified":"2011-08-01T21:32:44.882Z",
"location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"e180ee84f0671b1\""
},
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
},
"userName":"bjensen"
}
With the returned ETag, clients MAY choose to retrieve the resource
only if the resource has been modified.
Conditional retrieval example using If-None-Match [14] header: Conditional retrieval example using If-None-Match Section 14.26
[RFC2616] 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 client
Consumer MUST supply an If-Match [15] header for PUT and PATCH MUST supply an If-Match Section 14.24 [RFC2616] header for PUT and
operations to ensure that the requested operation succeeds only if PATCH operations to ensure that the requested operation succeeds only
the supplied ETag matches the latest Service Provider Resource; e.g., if the supplied ETag matches the latest service provider resource;
If-Match: W/"e180ee84f0671b1" e.g., 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 48, line 14 skipping to change at page 52, line 37
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
A single Service Provider may expose the SCIM protocol to multiple A single service provider may expose the SCIM protocol to multiple
Consumers. Depending on the nature of the service, the Consumers may clients. Depending on the nature of the service, the clients may
have authority to access and alter Resources initially created by have authority to access and alter resources initially created by
other Consumers. Alternatively, Consumers may expect to access other clients. Alternatively, clients may expect to access disjoint
disjoint sets of Resources, and may expect that their resources are sets of resources, and may expect that their resources are
inaccessible by other Consumers. These scenarios are called "multi- inaccessible by other clients. These scenarios are called "multi-
tenancy", where each Consumer is understood to be or represent a tenancy", where each client is understood to be or represent a
"tenant" of the Service Provider. Consumers may also be multi- "tenant" of the service provider. Clients may also be multi-
tenanted. tenanted.
The following common cases may occur: The following common cases may occur:
1. All Consumers share all Resources (no tenancy) 1. All clients share all resources (no tenancy)
2. Each single client creates and accesses a private subset of
2. Each single Consumer creates and accesses a private subset of resources (1 client:1 Tenant)
Resources (1 Consumer:1 Tenant)
3. Sets of Consumers share sets of Resources (M Consumers:1 Tenant) 3. Sets of clients share sets of resources (M clients:1 Tenant)
4. One Consumer to Multiple Tenants (1 Consumer:M Tenants) 4. One client to Multiple Tenants (1 client:M Tenants)
Service Providers may implement any subset of the above cases. Service providers may implement any subset of the above cases.
Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a
scheme for multi-tenancy. scheme for multi-tenancy.
The SCIM protocol does not prescribe the mechanisms whereby Consumers The SCIM protocol does not prescribe the mechanisms whereby clients
and Service Providers interact for: and service providers interact for:
o Registering or provisioning Tenants o Registering or provisioning Tenants
o Associating a subset of Consumers with a subset of the Tenants o Associating a subset of clients with a subset of the Tenants
o Indicating which tenant is associated with the data in a request o Indicating which tenant is associated with the data in a request
or response, or indicating which Tenant is the subject of a query or response, or indicating which Tenant is the subject of a query
o Implementers are encouraged to use mechanisms which comply with o Implementers are encouraged to use mechanisms which comply with
RESTful conventions. RESTful conventions.
4.1. Associating Consumers to Tenants 4.1. Associating Clients to Tenants
The Service Provider MAY use the authentication mechanism (Section 2) The service provider MAY use the authentication mechanism (Section 2)
to determine the identity of the Consumer, and thus infer the to determine the identity of the client, and thus infer the
associated Tenant. associated Tenant.
For implementations where a Consumer is associated with more than one For implementations where a client is associated with more than one
Tenant, the Service Provider MAY use one of the following methods for Tenant, the service provider MAY use one of the following methods for
explicit specification of the Tenant. explicit specification of the Tenant.
If any of these methods of allowing the Consumer to explicitly If any of these methods of allowing the client to explicitly specify
specify the Tenant are employed, the Service Provider should ensure the Tenant are employed, the service provider should ensure that
that access controls are in place to prevent or allow cross-tenant access controls are in place to prevent or allow cross-tenant use
use cases. cases.
The Service Provider should consider precedence in cases where a The service provider should consider precedence in cases where a
Consumer may explicitly specify a Tenant while being implicitly client may explicitly specify a Tenant while being implicitly
associated with a different Tenant. associated with a different Tenant.
4.1.1. URL Prefix Example 4.1.1. URL Prefix Example
https://www.example.com/Tenants/{tenant_id}/v1/Users https://www.example.com/Tenants/{tenant_id}/v2/Users
4.1.2. Subdomain Example 4.1.2. Subdomain Example
https://{tenant_id}.example.com/v1/Groups https://{tenant_id}.example.com/v2/Groups
4.1.3. HTTP Header 4.1.3. HTTP Header
The Service Provider may recognize a {tenant_id} provided by the The service provider may recognize a {tenant_id} provided by the
Consumer in the HTTP Header "SCIM_TENANT_ID" as the indicator of the client in the HTTP Header "SCIM_TENANT_ID" as the indicator of the
desired target Tenant. desired target Tenant.
In all of these methods, the {tenant_id} is a unique identifier for In all of these methods, the {tenant_id} is a unique identifier for
the Tenant as defined by the Service Provider. the Tenant as defined by the service provider.
4.2. SCIM Identifiers with Multiple Tenants 4.2. SCIM Identifiers with Multiple Tenants
Considerations for a Multi-Tenant Implementation: Considerations for a Multi-Tenant Implementation:
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 client, is required to be unique ONLY
ONLY within the Resources associated with the associated Tenant. 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] [16]. SCIM Resources considerations found in Section 15 of [RFC2616]. 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 clients 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 [17]] is the most recent version, writing, TLS version 1.2 [RFC5246]] is the most recent version, but
but has very limited actual deployment, and might not be readily has very limited actual deployment, and might not be readily
available in implementation toolkits. TLS version 1.0 [RFC2246 [18]] available in implementation toolkits. TLS version 1.0 [[RFC2246]] is
is the most widely deployed version, and will give the broadest the most widely deployed version, and will give the broadest
interoperability. interoperability.
6. Contributors 6. References
6.1. Normative References
[I-D.ietf-httpbis-p2-semantics]
Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Semantics and Content", draft-ietf-
httpbis-p2-semantics-25 (work in progress), November 2013.
[I-D.reschke-http-status-308]
Reschke, J., "The Hypertext Transfer Protocol (HTTP)
Status Code 308 (Permanent Redirect)", draft-reschke-http-
status-308-07 (work in progress), March 2012.
[IANA.Language]
Internet Assigned Numbers Authority (IANA), "Language
Subtag Registry", 2005.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
RFC 2246, January 1999.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3896] Nicklass, O., "Definitions of Managed Objects for the DS3/
E3 Interface Type", RFC 3896, September 2004.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC
5789, March 2010.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, October 2012.
6.2. Informative References
[OpenSearch]
Clinton, D., "OpenSearch Protocol 1.1, Draft 5", .
[Order-Operations]
Wikipedia, "Order of Operations: Programming Languages", .
Appendix A. Contributors
Samuel Erdtman (samuel@erdtman.se) Samuel Erdtman (samuel@erdtman.se)
Patrick Harding (pharding@pingidentity.com) Patrick Harding (pharding@pingidentity.com)
7. Acknowledgments Appendix B. Acknowledgments
The editors would like to acknowledge the contribution and work of
the past draft editors:
Trey Drake, UnboundID
Chuck Mortimore, Salesforce
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 Appendix C. Change Log
Authors' Addresses [[This section to be removed prior to publication as an RFC]]
Trey Drake (editor) Draft 02 - KG - Addition of schema extensibility
UnboundID
Email: trey.drake@unboundid.com Draft 03 - PH - Revisions based on following tickets:
Chuck Mortimore 24 - Add filter negation
SalesForce
Email: cmortimore@salesforce.com 39 - Clarification on response for DELETE
Morteza Ansari
Cisco
Email: morteza.ansari@cisco.com 42 - Make root searches optional
49 - Add "ew" filter
50 - Filters for multi-valued complex attributes
51 - Search by Schema
53 - Standard use of term client (some was consumer)
55 - Redirect support (3xx)
56 - Make manager attribute consistent with other $ref attrs
57 - Update all "/v1" examples to '/v2"
59 - Fix capitalization per IETF editor practices
60 - Changed <eref> tags to normal <xref> and <reference> tags
Authors' Addresses
Kelly Grizzle Kelly Grizzle
SailPoint SailPoint
Email: kelly.grizzle@sailpoint.com Email: kelly.grizzle@sailpoint.com
Phil Hunt (editor)
Oracle Corporation
Email: phil.hunt@yahoo.com
Morteza Ansari
Cisco
Email: morteza.ansari@cisco.com
Erik Wahlstroem Erik Wahlstroem
Technology Nexus Technology Nexus
Email: erik.wahlstrom@nexussafe.com Email: erik.wahlstrom@nexussafe.com
Chuck Mortimore
Salesforce.com
Email: cmortimore@salesforce.com
 End of changes. 230 change blocks. 
1073 lines changed or deleted 1209 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/