draft-ietf-scim-api-15.txt   draft-ietf-scim-api-16.txt 
Network Working Group P. Hunt, Ed. Network Working Group P. Hunt, Ed.
Internet-Draft Oracle Internet-Draft Oracle
Intended status: Standards Track K. Grizzle Intended status: Standards Track K. Grizzle
Expires: August 14, 2015 SailPoint Expires: September 9, 2015 SailPoint
M. Ansari M. Ansari
Cisco Cisco
E. Wahlstroem E. Wahlstroem
Nexus Technology Nexus Technology
C. Mortimore C. Mortimore
Salesforce Salesforce
February 10, 2015 March 8, 2015
System for Cross-Domain Identity Management: Protocol System for Cross-Domain Identity Management: Protocol
draft-ietf-scim-api-15 draft-ietf-scim-api-16
Abstract Abstract
The System for Cross-Domain Identity Management (SCIM) specification The System for Cross-Domain Identity Management (SCIM) specification
is an HTTP based protocol that makes managing identities in multi- is an HTTP based protocol that makes managing identities in multi-
domain scenarios easier to support through a standardized services. domain scenarios easier to support through a standardized services.
Examples include but are not limited to enterprise to cloud service Examples include but are not limited to enterprise to cloud service
providers, and inter-cloud based scenarios. The specification suite providers, and inter-cloud based scenarios. The specification suite
seeks to build upon experience with existing schemas and deployments, seeks to build upon experience with existing schemas and deployments,
placing specific emphasis on simplicity of development and placing specific emphasis on simplicity of development and
skipping to change at page 1, line 48 skipping to change at page 1, line 48
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 August 14, 2015. This Internet-Draft will expire on September 9, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 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
skipping to change at page 2, line 28 skipping to change at page 2, line 28
described in the Simplified BSD License. described in the Simplified BSD License.
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 . . . . . . . . . . . . . . . . . . . . . . . 4 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4
2. Authentication and Authorization . . . . . . . . . . . . . . 4 2. Authentication and Authorization . . . . . . . . . . . . . . 4
3. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 5 3. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 6 3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 5
3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 9 3.2. SCIM Endpoints . . . . . . . . . . . . . . . . . . . . . 6
3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 9 3.3. Creating Resources . . . . . . . . . . . . . . . . . . . 8
3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 9 3.3.1. Resource Types . . . . . . . . . . . . . . . . . . . 10
3.2.2. Query Resources . . . . . . . . . . . . . . . . . . . 10 3.4. Retrieving Resources . . . . . . . . . . . . . . . . . . 10
3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 21 3.4.1. Retrieving a known Resource . . . . . . . . . . . . . 10
3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 24 3.4.2. Query Resources . . . . . . . . . . . . . . . . . . . 11
3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 25 3.4.3. Querying Resources Using HTTP POST . . . . . . . . . 22
3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 27 3.5. Modifying Resources . . . . . . . . . . . . . . . . . . . 25
3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 41 3.5.1. Replacing with PUT . . . . . . . . . . . . . . . . . 26
3.5. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 42 3.5.2. Modifying with PATCH . . . . . . . . . . . . . . . . 28
3.5.1. Circular Reference Processing . . . . . . . . . . . . 44 3.6. Deleting Resources . . . . . . . . . . . . . . . . . . . 42
3.5.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 47 3.7. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 43
3.5.3. Response and Error Handling . . . . . . . . . . . . . 51 3.7.1. Circular Reference Processing . . . . . . . . . . . . 45
3.5.4. Maximum Operations . . . . . . . . . . . . . . . . . 57 3.7.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 48
3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 58 3.7.3. Response and Error Handling . . . . . . . . . . . . . 52
3.7. Additional Operation Response Parameters . . . . . . . . 59 3.7.4. Maximum Operations . . . . . . . . . . . . . . . . . 58
3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 60 3.8. Data Input/Output Formats . . . . . . . . . . . . . . . . 59
3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 60 3.9. Additional Operation Response Parameters . . . . . . . . 60
3.10. HTTP Status and Error Response Handling . . . . . . . . . 61 3.10. Attribute Notation . . . . . . . . . . . . . . . . . . . 61
3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 65 3.11. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 61
3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 65 3.12. HTTP Status and Error Response Handling . . . . . . . . . 62
4. Service Provider Configuration Endpoints . . . . . . . . . . 67 3.13. API Versioning . . . . . . . . . . . . . . . . . . . . . 66
5. Preparation and Comparison of Internationalized Strings . . . 69 3.14. Versioning Resources . . . . . . . . . . . . . . . . . . 66
6. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 70 4. Service Provider Configuration Endpoints . . . . . . . . . . 68
6.1. Associating Clients to Tenants . . . . . . . . . . . . . 70 5. Preparation and Comparison of Internationalized Strings . . . 70
6.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 71 6. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 71
7. Security Considerations . . . . . . . . . . . . . . . . . . . 71 6.1. Associating Clients to Tenants . . . . . . . . . . . . . 71
7.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 71 6.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 72
7.2. Disclosure of Sensitive Information in URIs . . . . . . . 72 7. Security Considerations . . . . . . . . . . . . . . . . . . . 72
7.3. Anonymous Requests . . . . . . . . . . . . . . . . . . . 72 7.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 72
7.4. HTTP Considerations . . . . . . . . . . . . . . . . . . . 73 7.2. Disclosure of Sensitive Information in URIs . . . . . . . 73
7.5. Secure Storage and Handling of Sensitive Data . . . . . . 73 7.3. Anonymous Requests . . . . . . . . . . . . . . . . . . . 73
7.6. Case Insensitive Comparision & International Languages . 74 7.4. HTTP Considerations . . . . . . . . . . . . . . . . . . . 74
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 7.5. Secure Storage and Handling of Sensitive Data . . . . . . 74
8.1. Media Type Registration . . . . . . . . . . . . . . . . . 74 7.6. Case Insensitive Comparision & International Languages . 75
8.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 75 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 75
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 76 8.1. Media Type Registration . . . . . . . . . . . . . . . . . 75
9.1. Normative References . . . . . . . . . . . . . . . . . . 76 8.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 76
9.2. Informative References . . . . . . . . . . . . . . . . . 77 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 77
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 78 9.1. Normative References . . . . . . . . . . . . . . . . . . 77
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 78 9.2. Informative References . . . . . . . . . . . . . . . . . 78
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 78 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 79
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 79
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 79
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 83
1. Introduction and Overview 1. Introduction and Overview
The SCIM Protocol is an application-level, HTTP protocol for The SCIM Protocol is an application-level, HTTP protocol for
provisioning and managing identity data on the web and in cross- provisioning and managing identity data on the web and in cross-
domain environments such as enterprise to cloud, or inter-cloud domain environments such as enterprise to cloud, or inter-cloud
scenarios. The protocol supports creation, modification, retrieval, scenarios. The protocol supports creation, modification, retrieval,
and discovery of core identity resources such as Users and Groups, as and discovery of core identity resources such as Users and Groups, as
well as custom resources and resource extensions. well as custom resources and resource extensions.
skipping to change at page 4, line 32 skipping to change at page 4, line 32
scheme, a domain name and some initial path [RFC3986]. Example: scheme, a domain name and some initial path [RFC3986]. Example:
"https://example.com/scim/" "https://example.com/scim/"
For readability, all examples in this document are expressed For readability, all examples in this document are expressed
assuming the SCIM service root and the server root are the same assuming the SCIM service root and the server root are the same
(no path pre-fix). It is expected that SCIM servers may be (no path pre-fix). It is expected that SCIM servers may be
deployed using any URI path prefix. For example, a SCIM server deployed using any URI path prefix. For example, a SCIM server
might be have a prefix of "https://example.com/", or might be have a prefix of "https://example.com/", or
"https://example.com/scim/tenancypath/". Additionally client may "https://example.com/scim/tenancypath/". Additionally client may
also apply a version number to the server root prefix (see also apply a version number to the server root prefix (see
Section 3.11 ). Section 3.13 ).
2. Authentication and Authorization 2. Authentication and Authorization
Because SCIM builds on the HTTP protocol, it does not itself define a Because SCIM builds on the HTTP protocol, it does not itself define a
scheme for authentication and authorization. SCIM depends on scheme for authentication and authorization. SCIM depends on
standard HTTP authentication schemes. Implementers SHOULD support standard HTTP authentication schemes. Implementers SHOULD support
existing authentication/authorization schemes. In particular, OAuth2 existing authentication/authorization schemes. In particular, OAuth2
(see [RFC6749], [RFC6750]) is RECOMMENDED. Appropriate security (see [RFC6749], [RFC6750]) is RECOMMENDED. Appropriate security
considerations of the selected authentication and authorization considerations of the selected authentication and authorization
schemes SHOULD be taken. Because this protocol uses HTTP response schemes SHOULD be taken. Because this protocol uses HTTP response
skipping to change at page 5, line 16 skipping to change at page 5, line 16
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
When processing requests, the service provider SHOULD consider the When processing requests, the service provider SHOULD consider the
subject performing the request and whether the action is appropriate subject performing the request and whether the action is appropriate
given the subject and the resource affected by the request. The given the subject and the resource affected by the request. The
subject performing the request is usually determined from the subject performing the request is usually determined from the
"Authorization" header present in the request. "Authorization" header present in the request.
3. SCIM Protocol 3. SCIM Protocol
3.1. Introduction
SCIM is a protocol that is based on HTTP protocol [RFC7230]. Along
with HTTP headers and URIs, SCIM uses JSON [RFC7159] payloads to
convey both SCIM resources, as well as protocol specific payload
messages that convey request parameters and response information such
as errors. Both resources and messages are passed in the form of
JSON based structures in the message body of an HTTP request or
response. To identify this content, SCIM uses a media type of
"application/scim+json" (see Section 8.1).
A SCIM "resource" is a JSON object that may be created, maintained,
and retrieved through HTTP request methods as described in this
document. Each JSON resource representation contains a "schemas"
attribute that contains a list of one or more URIs that indicate
included SCIM schemas that are used to indicate the attributes
contained within a resource. Specific information about what
attributes are defined within a schema MAY be obtained by querying a
SCIM service provider's "/Schemas" endpoint for a schema definition
(see Section 8.7 [I-D.ietf-scim-core-schema]). Responses from this
endpoint describe how a service provider supports a schema and in
particular how attribute qualities such as cardinality, case-
exactness, mutability, uniqueness, returnability, and whether an
attribute is required. While SCIM schemas and associated extension
model are defined in [I-D.ietf-scim-core-schema], SCIM clients should
expect that some attribute schema MAY change from service provider to
service provider, particularly across administrative domains. In
cases where SCIM may be used as an open protocol in front of an
application service, it is quite reasonable to expect that some
service providers MAY only support a sub-set of the schema defined in
[I-D.ietf-scim-core-schema].
A SCIM message conveys protocol parameters about a SCIM request or
response that are defined by this specification. As with a SCIM
resource, a SCIM message is a JSON object that contains a "schemas"
attribute with a URI whose namespace prefix that MUST begin with
"urn:ietf:params:scim:api:". As SCIM protocol messages are fixed and
defined by SCIM specifications and registered extensions, SCIM
message schemas using the above prefix URN SHALL NOT be discoverable
using the "/Schemas" endpoint.
As SCIM is intended for use within cross-domain environments where
schema and implementations MAY vary, techniques such as document
validation, such as in [XML-Schema], are not recommended. A SCIM
service provider interprets a request in the context of its own
schema (which may be different from the client's schema) and
following the defined processing rules for each request. The
following sections in this document define the processing rules for
SCIM and provide allowances for schema differences where appropriate.
For example, in a SCIM PUT request, "readOnly" attributes are
ignored, while "readWrite" attributes are updated. There is no need
for a SCIM client to discover which attributes are "readOnly" and
does not need to remove them from a PUT request in advance in order
to be accepted. Similarly a SCIM client SHOULD NOT expect a service
provider to return SCIM resources with exactly the same schema and
values as submitted. SCIM responses SHALL reflect resource state as
interpreted by the SCIM service provider.
3.2. SCIM Endpoints
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 managing resources defined in the core schema; i.e., "User" and
"Group" resources correspond to "/Users" and "/Groups" respectively. "Group" resources correspond to "/Users" and "/Groups" respectively.
Service providers that support extended resources SHOULD define Service providers that support extended resources SHOULD define
resource endpoints using the convention of pluralizing the resource resource endpoints using the convention of pluralizing the resource
name defined in the extended schema by appending an 's'. Given there name defined in the extended schema by appending an 's'. Given there
are cases where resource pluralization is ambiguous; e.g., a resource are cases where resource pluralization is ambiguous; e.g., a resource
named "Person" is legitimately "Persons" and "People". Clients named "Person" is legitimately "Persons" and "People". Clients
SHOULD discover resource endpoints via the "/ResourceTypes" endpoint. SHOULD discover resource endpoints via the "/ResourceTypes" endpoint.
skipping to change at page 6, line 7 skipping to change at page 7, line 12
PATCH PATCH
Modifies a resource with a set of client specified changes Modifies a resource with a set of client specified changes
(partial update). (partial update).
DELETE DELETE
Deletes a resource. Deletes a resource.
Resource Endpoint Operations Description Resource Endpoint Operations Description
-------- ---------------- ---------------------- -------------------- -------- ---------------- ---------------------- --------------------
User /Users GET (Section 3.2.1), Retrieve, Add, User /Users GET (Section 3.4.1), Retrieve, Add,
POST (Section 3.1), Modify Users POST (Section 3.3), Modify Users
PUT (Section 3.3.1), PUT (Section 3.5.1),
PATCH (Section 3.3.2), PATCH (Section 3.5.2),
DELETE (Section 3.4) DELETE (Section 3.6)
Group /Groups GET (Section 3.2.1), Retrieve, Add, Group /Groups GET (Section 3.4.1), Retrieve, Add,
POST (Section 3.1), Modify Groups POST (Section 3.3), Modify Groups
PUT (Section 3.3.1), PUT (Section 3.5.1),
PATCH (Section 3.3.2), PATCH (Section 3.5.2),
DELETE (Section 3.4) DELETE (Section 3.6)
Self /Me GET, POST, PUT, PATCH, Alias for operations Self /Me GET, POST, PUT, PATCH, Alias for operations
DELETE (Section 3.9) against a resource DELETE (Section 3.11) against a resource
mapped to an mapped to an
authenticated authenticated
Subject (e.g. User). Subject (e.g. User).
Service /ServiceProvider GET (Section 4) Retrieve service Service /ServiceProvider GET (Section 4) Retrieve service
Provider Config provider's Provider Config provider's
Config configuration Config configuration
Resource /ResourceTypes GET (Section 4) Retrieve supported Resource /ResourceTypes GET (Section 4) Retrieve supported
Type resource types Type resource types
Schema /Schemas GET (Section 4) Retrieve one or more Schema /Schemas GET (Section 4) Retrieve one or more
supported schemas. supported schemas.
Bulk /Bulk POST (Section 3.5) Bulk updates to one Bulk /Bulk POST (Section 3.7) Bulk updates to one
or more resources or more resources
Search [prefix]/.search POST (Section 3.2.3) Search from system Search [prefix]/.search POST (Section 3.4.3) Search from system
root or within a root or within a
resource endpoint resource endpoint
for one or more for one or more
resource types using resource types using
POST. POST.
Table 1: Defined endpoints Table 1: Defined endpoints
All requests to the service provider are made via HTTP Methods as per All requests to the service provider are made via HTTP Methods as per
Section 4.3 [RFC7231] on a URL derived from the Base URL. Responses Section 4.3 [RFC7231] on a URL derived from the Base URL. Responses
are returned in the body of the HTTP response, formatted as JSON. are returned in the body of the HTTP response, formatted as JSON.
Error status codes SHOULD be transmitted via the HTTP status code of Error status codes SHOULD be transmitted via the HTTP status code of
the response (if possible), and SHOULD also be specified in the body the response (if possible), and SHOULD also be specified in the body
of the response (see Section 3.10). of the response (see Section 3.12).
3.1. Creating Resources 3.3. Creating Resources
To create new resources, clients send HTTP POST requests to the To create new resources, clients send HTTP POST requests to the
resource endpoint such as: "/Users" or "/Groups". resource endpoint such as: "/Users" or "/Groups".
The server SHALL process attributes according to the following The server SHALL process attributes according to the following
mutability rules: mutability rules:
o For attributes in the request body, whose mutability is o For attributes in the request body, whose mutability is
"readOnly", SHALL be ignored. "readOnly", SHALL be ignored.
skipping to change at page 7, line 36 skipping to change at page 8, line 41
representation of the newly created resource. The URI of the created representation of the newly created resource. The URI of the created
resource SHALL included in the HTTP "Location" header and in JSON resource SHALL included in the HTTP "Location" header and in JSON
resource representation under the attribute "meta.location". Since resource representation under the attribute "meta.location". Since
the server is free to alter and/or ignore POSTed content, returning the server is free to alter and/or ignore POSTed content, returning
the full representation can be useful to the client, enabling it to the full representation can be useful to the client, enabling it to
correlate the client and server views of the new resource. correlate the client and server views of the new resource.
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 an HTTP Status duplicate "userName", the service provider MUST return an HTTP Status
409, with "scimType" error code of "uniqueness" as per Section 3.10. 409, with "scimType" error code of "uniqueness" as per Section 3.12.
Below, in the following example, a client sends a POST request Below, in the following example, a client sends a POST request
containing a "User" to the "/Users" endpoint. containing a "User" to the "/Users" endpoint.
POST /Users HTTP/1.1 POST /Users HTTP/1.1
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
skipping to change at page 9, line 5 skipping to change at page 10, line 5
"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.3.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 HTTP service provider to the "resourceType" SHALL be set by the HTTP 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.4. Retrieving Resources
Resources are retrieved via opaque, unique URLs or via Query. The Resources are retrieved via opaque, unique URLs or via Query (see
attributes returned are defined in the server's attribute schema (see Section 3.4.2). The attributes returned are defined in the server's
Section 10 [I-D.ietf-scim-core-schema]) and request parameters (see attribute schema (see Section 10 [I-D.ietf-scim-core-schema]) and
Section 3.7). By default, resource attributes returned in a response request parameters (see Section 3.9). By default, resource
are those whose schema "returned" setting is "always" or "default". attributes returned in a response are those whose schema "returned"
setting is "always" or "default".
3.2.1. Retrieving a known Resource 3.4.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}", or resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}", or
"/Schemas/{id}". "/Schemas/{id}".
If the resource exists the server responds with HTTP Status code 200 If the resource exists the server responds with HTTP Status code 200
(OK) and includes the result in the body of the response. (OK) 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.
skipping to change at page 10, line 43 skipping to change at page 11, line 43
} }
], ],
"emails":[ "emails":[
{ {
"value":"bjensen@example.com", "value":"bjensen@example.com",
"type":"work" "type":"work"
} }
] ]
} }
3.2.2. Query Resources 3.4.2. Query Resources
The SCIM protocol defines a standard set of query parameters that can The SCIM protocol defines a standard set of query parameters that can
be used to filter, sort, and paginate to return zero or more be used to filter, sort, and paginate to return zero or more
resources in a query response. Queries MAY be made against a single resources in a query response. Queries MAY be made against a single
resource or a resource type endpoint (e.g. "/Users"). SCIM service resource or a resource type endpoint (e.g. "/Users"). SCIM service
providers MAY support additional query parameters not specified here providers MAY support additional query parameters not specified here
and SHOULD ignore any query parameters they do not recognize. and SHOULD ignore any query parameters they do not recognize.
Responses MUST be identified using the following URI: Responses MUST be identified using the following URI:
"urn:ietf:params:scim:api:messages:2.0:ListResponse". The following "urn:ietf:params:scim:api:messages:2.0:ListResponse". The following
attributes are defined for responses: attributes are defined for 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.4.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.4.2.4) is requested. REQUIRED
if "totalResults" is non-zero. if "totalResults" is non-zero.
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 when partial results returned due to of list results. REQUIRED when partial results returned due to
pagination. pagination.
itemsPerPage The number of resources returned in a list response itemsPerPage The number of resources returned in a list response
page. REQUIRED when partial results returned due to pagination. page. REQUIRED when partial results returned due to pagination.
A query that does not return any matches SHALL return success (HTTP A query that does not return any matches SHALL return success (HTTP
skipping to change at page 12, line 5 skipping to change at page 13, line 5
"Resources":[ "Resources":[
{ {
"userName":"bjensen" "userName":"bjensen"
}, },
{ {
"userName":"jsmith" "userName":"jsmith"
} }
] ]
} }
3.2.2.1. Query Endpoints 3.4.2.1. Query Endpoints
Queries MAY be performed against a SCIM resource object, a resource Queries MAY be performed against a SCIM resource object, a resource
type endpoint, or a SCIM server root. For example: type endpoint, or a SCIM server root. For example:
"/Users/{id}" "/Users/{id}"
"/Users" "/Users"
"/Groups" "/Groups"
skipping to change at page 12, line 31 skipping to change at page 13, line 31
filter=(meta.resourceType eq User) or (meta.resourceType eq Group) filter=(meta.resourceType eq User) or (meta.resourceType eq Group)
If a SCIM service provider determines that too many results would be If a SCIM service provider determines that too many results would be
returned (e.g. because a client queried a resource type endpoint or returned (e.g. because a client queried a resource type endpoint or
the server base URI), the server SHALL reject the request by the server base URI), the server SHALL reject the request by
returning an HTTP response with "status" 400 and json attribute returning an HTTP response with "status" 400 and json attribute
"scimType" set to "tooMany" (see Table 8). "scimType" set to "tooMany" (see Table 8).
When processing query operations across endpoints that include more When processing query operations across endpoints that include more
than one SCIM resource type (e.g. a query from the server root than one SCIM resource type (e.g. a query from the server root
endpoint), filters MUST be processed as outlined in Section 3.2.2.2. endpoint), filters MUST be processed as outlined in Section 3.4.2.2.
For filtered attributes that are not part of a particular resource For filtered attributes that are not part of a particular resource
type, the service provider SHALL treat the attribute as if there is type, the service provider SHALL treat the attribute as if there is
no attribute value. For example, a presence or equality filter for no attribute value. For example, a presence or equality filter for
an undefined attribute evaluates as FALSE. an undefined attribute evaluates as FALSE.
3.2.2.2. Filtering 3.4.2.2. Filtering
Filtering is an OPTIONAL parameter for SCIM service providers. Filtering is an OPTIONAL parameter for SCIM service providers.
Clients MAY discover service provider filter capabilities by looking Clients MAY discover service provider filter capabilities by looking
at the "filter" attribute of the "ServiceProviderConfig" (see at the "filter" attribute of the "ServiceProviderConfig" (see
Section 8 [I-D.ietf-scim-core-schema]). Clients MAY request a subset Section 8 [I-D.ietf-scim-core-schema]). Clients MAY request a subset
of resources by specifying the "filter" query parameter containing a of resources by specifying the "filter" 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 filter expression SHALL be returned. The expression language that is
used in the filter parameter supports references to attributes and used in the filter parameter supports references to attributes and
literals. literals.
skipping to change at page 17, line 7 skipping to change at page 18, line 7
Filters MUST be evaluated using standard order of operations Filters MUST be evaluated using standard order of operations
[Order-Operations]. Attribute operators have the highest precedence, [Order-Operations]. Attribute operators have the highest precedence,
followed by the grouping operator (i.e, parentheses), followed by the followed by the grouping operator (i.e, parentheses), followed by the
logical AND 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.10). 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 client 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 client 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.'
skipping to change at page 19, line 5 skipping to change at page 20, line 5
filter=userType eq "Employee" and (emails.type eq "work") filter=userType eq "Employee" and (emails.type eq "work")
filter=userType eq "Employee" and emails[type eq "work" and filter=userType eq "Employee" and emails[type eq "work" and
value co "@example.com"] value co "@example.com"]
filter=emails[type eq "work" and value co "@example.com"] or filter=emails[type eq "work" and value co "@example.com"] or
ims[type eq "xmpp" and value co "@foo.com"] ims[type eq "xmpp" and value co "@foo.com"]
Figure 2: Example Filters Figure 2: Example Filters
3.2.2.3. Sorting 3.4.2.3. Sorting
Sort is OPTIONAL. Sorting allows clients 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 (see Section 2.2 [I-D.ietf-scim-core-schema]), if any, attribute (see Section 2.2 [I-D.ietf-scim-core-schema]), if any,
or else the first value in the list, if any. If the attribute is or else the first value in the list, if any. If the attribute is
complex the attribute name must be a path to a sub-attribute in complex the attribute name must be a path to a sub-attribute in
standard attribute notation (Section 3.8) ; e.g., standard attribute notation (Section 3.10) ; 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
case exact string. "sortOrder" MUST sort according to the case exact string. "sortOrder" MUST sort according to the
attribute type; i.e., for case insensitive attributes, sort the attribute type; i.e., for case insensitive attributes, sort the
result using case insensitive, unicode alphabetic sort order, with result using case insensitive, unicode alphabetic sort order, with
no specific locale implied and for case exact attribute types, no specific locale implied and for case exact attribute types,
sort the result using case sensitive, Unicode alphabetic sort sort the result using case sensitive, Unicode alphabetic sort
order. order.
3.2.2.4. Pagination 3.4.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 client or service numbers of resources so as not to overwhelm the client or service
provider. Pagination is not session based hence clients SHOULD never provider. Pagination is not session based hence clients SHOULD never
assume repeatable results. For example, a request for a list of 10 assume repeatable results. For example, a request for a list 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 [OpenSearch]. Protocol [OpenSearch].
skipping to change at page 21, line 23 skipping to change at page 22, line 23
"Resources":[{ "Resources":[{
... ...
}] }]
} }
Figure 3: ListResponse format for returning multiple resources Figure 3: ListResponse format for returning multiple resources
Given the example above, to continue paging set the startIndex to 11 Given the example above, to continue paging set the startIndex to 11
and re-fetch; i.e., /Users?startIndex=11&count=10 and re-fetch; i.e., /Users?startIndex=11&count=10
3.2.2.5. Attributes 3.4.2.5. Attributes
The following attributes control which attributes SHALL be returned The following attributes control which attributes SHALL be returned
with a returned resource. SCIM clients MAY use up to one of these with a returned resource. SCIM clients MAY use up to one of these
two OPTIONAL parameters which MUST be supported by SCIM service two OPTIONAL parameters which MUST be supported by SCIM service
providers: providers:
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 overriding the set resource attributes to return in the response overriding the set
of attributes that would be returned by default. Attribute names of attributes that would be returned by default. Attribute names
MUST be in standard.attribute notation (Section 3.8) form. See MUST be in standard.attribute notation (Section 3.10) form. See
additional retrieval query parameters (Section 3.7). additional retrieval query parameters (Section 3.9).
excludedAttributes A multi-valued list of strings indicating the excludedAttributes A multi-valued list of strings indicating the
names of resource attributes to be removed from the default set of names of resource attributes to be removed from the default set of
attributes to return. This parameter SHALL have no effect on attributes to return. This parameter SHALL have no effect on
attributes whose schema "returned" setting is "always" see Server attributes whose schema "returned" setting is "always" see Server
Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in
standard attribute notation (Section 3.8) form. See additional standard attribute notation (Section 3.10) form. See additional
retrieval query parameters (Section 3.7). retrieval query parameters (Section 3.9).
3.2.3. Querying Resources Using HTTP POST 3.4.3. Querying Resources Using HTTP POST
Clients MAY execute queries without passing parameters on the URL by Clients MAY execute queries without passing parameters on the URL by
using the HTTP POST verb combined with the '/.search' path extension. using the HTTP POST verb combined with the '/.search' path extension.
The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL
be used to indicate the HTTP POST verb is intended to be a query be used to indicate the HTTP POST verb is intended to be a query
operation. operation.
To create a new query result set, a SCIM client sends an HTTP POST To create a new query 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.4.2.
Query requests MUST be identified using the following URI: Query requests MUST be identified using the following URI:
'urn:ietf:params:scim:api:messages:2.0:SearchRequest'. The following 'urn:ietf:params:scim:api:messages:2.0:SearchRequest'. The following
attributes are defined for query requests: attributes are defined for query 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 overriding the set resource attributes to return in the response overriding the set
of attributes that would be returned by default. Attribute names of attributes that would be returned by default. Attribute names
MUST be in standard attribute notation (Section 3.8) form. See MUST be in standard attribute notation (Section 3.10) form. See
additional retrieval query parameters (Section 3.7). OPTIONAL. additional retrieval query parameters (Section 3.9). OPTIONAL.
excludedAttributes A multi-valued list of strings indicating the excludedAttributes A multi-valued list of strings indicating the
names of resource attributes to be removed from the default set of names of resource attributes to be removed from the default set of
attributes to return. This parameter SHALL have no effect on attributes to return. This parameter SHALL have no effect on
attributes whose schema "returned" setting is "always" see Server attributes whose schema "returned" setting is "always" see Server
Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in
standard attribute notation (Section 3.8) form. See additional standard attribute notation (Section 3.10) form. See additional
retrieval query parameters (Section 3.7). OPTIONAL. retrieval query parameters (Section 3.9). 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.4.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.10) form. See sorting
(Section 3.2.2.3). OPTIONAL. (Section 3.4.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
"descending". See sorting (Section 3.2.2.3). OPTIONAL. "descending". See sorting (Section 3.4.2.3). OPTIONAL.
startIndex An integer indicating the 1-based index of the first startIndex An integer indicating the 1-based index of the first
query result. See pagination (Section 3.2.2.4). OPTIONAL. query result. See pagination (Section 3.4.2.4). OPTIONAL.
count An integer indicating the desired maximum number of query count An integer indicating the desired maximum number of query
results per page. See pagination (Section 3.2.2.4). OPTIONAL. results per page. See pagination (Section 3.4.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.4.2.
The following example shows an HTTP POST Query request with search The following example shows an HTTP POST Query 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/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
skipping to change at page 24, line 42 skipping to change at page 25, line 42
"lastModified": ... "lastModified": ...
}, },
"displayName":"Smith Family" "displayName":"Smith Family"
}, },
... ...
] ]
} }
Figure 5: Example POST Query Response Figure 5: Example POST Query Response
3.3. Modifying Resources 3.5. 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 respectively. Implementers MUST support PUT as specified in
Section 4.3 [RFC7231]. Resources such as Groups may be very large Section 4.3 [RFC7231]. Resources such as Groups may be very large
hence implementers SHOULD support HTTP PATCH [RFC5789] to enable hence implementers SHOULD support HTTP PATCH [RFC5789] to enable
partial resource modifications. partial resource modifications.
3.3.1. Replacing with PUT 3.5.1. Replacing with PUT
HTTP PUT is used to perform a full update of a resource's attributes. HTTP PUT is used to perform a full update of a resource's attributes.
Clients that MAY have previously retrieved the entire resource in Clients that MAY have previously retrieved the entire resource in
advance and revised it, MAY replace the resource using an HTTP PUT. advance and revised it, MAY replace the resource using an HTTP PUT.
Because SCIM resource identifiers are typically assigned by the Because SCIM resource identifiers are typically assigned by the
service provider, HTTP PUT MUST NOT be used to create new resources. service provider, HTTP PUT MUST NOT be used to create new resources.
As the operation intent is to replace all attributes, SCIM clients As the operation intent is to replace all attributes, SCIM clients
MAY send all attributes regardless of each attribute's mutability. MAY send all attributes regardless of each attribute's mutability.
The server will apply attribute by attribute replace according to the The server will apply attribute by attribute replace according to the
skipping to change at page 27, line 40 skipping to change at page 28, line 40
"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": "location":
"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"b431af54f0671a2\"" "version":"W\/\"b431af54f0671a2\""
} }
} }
3.3.2. Modifying with PATCH 3.5.2. Modifying with PATCH
HTTP PATCH is an OPTIONAL server function that enables clients to HTTP PATCH is an OPTIONAL server function that enables clients to
update one or more attributes of a SCIM resource using a sequence of update one or more attributes of a SCIM resource using a sequence of
operations to "add", "remove", or "replace" values. The general form operations to "add", "remove", or "replace" values. The general form
of the SCIM patch request is based on JavaScript Object Notation of the SCIM patch request is based on JavaScript Object Notation
(JSON) Patch [RFC6902]. One difference between SCIM patch and JSON (JSON) Patch [RFC6902]. One difference between SCIM patch and JSON
patch is that SCIM servers do not support array indexing and may not patch is that SCIM servers do not support array indexing and may not
support all [RFC6902] operation types. support all [RFC6902] operation types.
The body of each request MUST contain the following "schemas" The body of each request MUST contain the following "schemas"
skipping to change at page 28, line 50 skipping to change at page 29, line 50
OPTIONAL for "add" and "replace" and is REQUIRED for "remove" OPTIONAL for "add" and "replace" and is REQUIRED for "remove"
operations. See relevant operation sections below for details. operations. See relevant operation sections below for details.
The "path" attribute is described by the following ABNF syntax rule: The "path" attribute is described by the following ABNF syntax rule:
PATH = attrPath / valuePath [subAttr] PATH = attrPath / valuePath [subAttr]
Figure 7: SCIM Patch PATH Rule Figure 7: SCIM Patch PATH Rule
The ABNF rules, "attrPath", "valuePath", and "subAttr" are defined in The ABNF rules, "attrPath", "valuePath", and "subAttr" are defined in
Section 3.2.2.2. The "valuePath" rule allows specific values of a Section 3.4.2.2. The "valuePath" rule allows specific values of a
complex, multi-valued attribute to be selected. complex, multi-valued attribute to be selected.
Valid examples of "path" values are as follows: Valid examples of "path" values are as follows:
"path":"members" "path":"members"
"path":"name.familyName" "path":"name.familyName"
"path":"addresses[type eq \"work\"]" "path":"addresses[type eq \"work\"]"
skipping to change at page 29, line 29 skipping to change at page 30, line 29
Figure 8: Example Path Values Figure 8: Example Path Values
Each operation against an attribute MUST be compatible with the Each operation against an attribute MUST be compatible with the
attribute's mutability and schema as defined in the Attribute Types attribute's mutability and schema as defined in the Attribute Types
Section of [I-D.ietf-scim-core-schema]. For example, a client MUST Section of [I-D.ietf-scim-core-schema]. For example, a client MUST
NOT modify an attribute that has mutability "readOnly" or NOT modify an attribute that has mutability "readOnly" or
"immutable". However, a client MAY "add" a value to an "immutable" "immutable". However, a client MAY "add" a value to an "immutable"
attribute if the attribute had no previous value. An operation that attribute if the attribute had no previous value. An operation that
is not compatibile with an attribute's mutability or schema SHALL is not compatibile with an attribute's mutability or schema SHALL
return the appropriate HTTP response status code and a JSON detail return the appropriate HTTP response status code and a JSON detail
error response as defined in Section 3.10. error response as defined in Section 3.12.
The attribute notation rules described in Section 3.8 apply for The attribute notation rules described in Section 3.10 apply for
describing attribute paths. For all operations, the value of the describing attribute paths. For all operations, the value of the
"schemas" attribute on the SCIM service provider's representation of "schemas" attribute on the SCIM service provider's representation of
the resource SHALL be assumed by default. If one of the PATCH the resource SHALL be assumed by default. If one of the PATCH
operations modifies the "schemas" attribute, subsequent operations operations modifies the "schemas" attribute, subsequent operations
SHALL assume the modified state of the "schemas" attribute. Clients SHALL assume the modified state of the "schemas" attribute. Clients
MAY implicitly modify the "schemas" attribute by adding (or MAY implicitly modify the "schemas" attribute by adding (or
replacing) an attribute with its fully qualified name including replacing) an attribute with its fully qualified name including
schema URN. For example, adding the attribute "urn:ietf:params:scim: schema URN. For example, adding the attribute "urn:ietf:params:scim:
schemas:extension:enterprise:2.0:User:employeeNumber", automatically schemas:extension:enterprise:2.0:User:employeeNumber", automatically
adds the value adds the value
skipping to change at page 30, line 16 skipping to change at page 31, line 16
"primary" attribute to "true", SHALL cause the server to "primary" attribute to "true", SHALL cause the server to
automatically set "primary" to "false" for any other values in the automatically set "primary" to "false" for any other values in the
array as only one value MAY be primary. array as only one value MAY be primary.
A patch request, regardless of the number of operations, SHALL be A patch request, regardless of the number of operations, SHALL be
treated as atomic. If a single operation encounters an error treated as atomic. If a single operation encounters an error
condition, the original SCIM resource MUST be restored, and a failure condition, the original SCIM resource MUST be restored, and a failure
status SHALL be returned. status SHALL be returned.
If a request fails, the server SHALL return an HTTP response status If a request fails, the server SHALL return an HTTP response status
code and a JSON detail error response as defined in Section 3.10. code and a JSON detail error response as defined in Section 3.12.
On successful completion, the server MUST return either a 200 OK On successful completion, 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 (Section 3.9) ) within the response body, or a 204 No Content
response code and the appropriate response headers for a successful response code and the appropriate response headers for a successful
patch request. The server MUST return a 200 OK if the "attributes" patch request. The server MUST return a 200 OK if the "attributes"
parameter is specified on the request. parameter is specified on the request.
3.3.2.1. Add Operation 3.5.2.1. Add Operation
The "add" operation is used to add a new attribute value to an The "add" operation is used to add a new attribute value to an
existing resource. existing resource.
The operation MUST contain a "value" member whose content specifies The operation MUST contain a "value" member whose content specifies
the value to be added. The value MAY be a quoted value OR it may be the value to be added. The value MAY be a quoted value OR it may be
a JSON object containing the sub-attributes of the complex attribute a JSON object containing the sub-attributes of the complex attribute
specified in the operation's "path". specified in the operation's "path".
The result of the add operation depends upon what the target location The result of the add operation depends upon what the target location
skipping to change at page 32, line 42 skipping to change at page 33, line 42
"nickname":"Babs" "nickname":"Babs"
}] }]
} }
In the above example, an additional value is added to the multi- In the above example, an additional value is added to the multi-
valued attribute "emails". The second attribute, "nickname" is added valued attribute "emails". The second attribute, "nickname" is added
to the User resource. If the resource already had an existing to the User resource. If the resource already had an existing
"nickname", the value is replaced per the processing rules above for "nickname", the value is replaced per the processing rules above for
single-valued attributes. single-valued attributes.
3.3.2.2. Remove Operation 3.5.2.2. Remove Operation
The "remove" operation removes the value at the target location The "remove" operation removes the value at the target location
specified by the required attribute "path". The operation performs specified by the required attribute "path". The operation performs
the following functions depending on the target location specified by the following functions depending on the target location specified by
"path" : "path" :
o If "path" is unspecified, the operation fails with HTTP status o If "path" is unspecified, the operation fails with HTTP status
"400" and "scimType" of "noTarget". "400" and "scimType" of "noTarget".
o If the target location is a single-value attribute, the attribute o If the target location is a single-value attribute, the attribute
skipping to change at page 33, line 29 skipping to change at page 34, line 29
o If the target location is a complex-multi-valued attribute and a o If the target location is a complex-multi-valued attribute and a
complex filter is specified based on the attribute's sub- complex filter is specified based on the attribute's sub-
attributes, the matching records are removed. Sub-attributes attributes, the matching records are removed. Sub-attributes
whose values have been removed SHALL be considered unassigned. If whose values have been removed SHALL be considered unassigned. If
the complex-multi-valued attribute has no remaining records, the the complex-multi-valued attribute has no remaining records, the
attribute SHALL be considered unassigned. attribute SHALL be considered unassigned.
If an attribute is removed or becomes unassigned and is defined as a If an attribute is removed or becomes unassigned and is defined as a
required attribute or a read-only attribute, the server SHALL return required attribute or a read-only attribute, the server SHALL return
an HTTP response status code and a JSON detail error response as an HTTP response status code and a JSON detail error response as
defined in Section 3.10 with a "scimType" error of "mutability". defined in Section 3.12 with a "scimType" error of "mutability".
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.
Remove a single member from a group. Some text removed for Remove a single member from a group. Some text removed for
skipping to change at page 36, line 38 skipping to change at page 37, line 38
}, },
{ {
"display": "James Smith", "display": "James Smith",
"$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210",
"value": "08e1d05d-121c-4561-8b96-473d93df9210" "value": "08e1d05d-121c-4561-8b96-473d93df9210"
}] }]
} }
] ]
} }
3.3.2.3. Replace Operation 3.5.2.3. Replace Operation
The "replace" operation replaces the value at the target location The "replace" operation replaces the value at the target location
specified by the "path". The operation performs the following specified by the "path". The operation performs the following
functions depending on the target location specified by "path" : functions depending on the target location specified by "path" :
o If the "path" parameter is omitted, the target is assumed to be o If the "path" parameter is omitted, the target is assumed to be
the resource itself. In this case, the "value" attribute SHALL the resource itself. In this case, the "value" attribute SHALL
contain a list of one or more attributes that are to be replaced. contain a list of one or more attributes that are to be replaced.
o If the target location is a single-value attribute, the attributes o If the target location is a single-value attribute, the attributes
skipping to change at page 41, line 35 skipping to change at page 42, line 35
}, },
{ {
"value":"babs@jensen.org", "value":"babs@jensen.org",
"type":"home" "type":"home"
} }
], ],
"nickname":"Babs" "nickname":"Babs"
}] }]
} }
3.4. Deleting Resources 3.6. Deleting Resources
Clients 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 SHOULD NOT consider the results. In addition the service provider SHOULD 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.
skipping to change at page 42, line 32 skipping to change at page 43, line 32
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"Errors":[ "Errors":[
{ {
"description": "description":
"Resource 2819c223-7f76-453a-919d-413861904646 not found", "Resource 2819c223-7f76-453a-919d-413861904646 not found",
"code":"404" "code":"404"
} }
] ]
} }
3.5. Bulk Operations 3.7. Bulk Operations
The SCIM bulk operation is an optional server feature that enables The SCIM bulk operation is an optional server feature that enables
clients to send a potentially large collection of resource operations clients to send a potentially large collection of resource operations
in a single request. The body of a a bulk operation contains a set in a single request. The body of a a bulk operation contains a set
of HTTP resource operations using one of the API supported HTTP of HTTP resource operations using one of the API supported HTTP
methods; i.e., POST, PUT, PATCH or DELETE. methods; i.e., POST, PUT, PATCH or DELETE.
Bulk requests are identified using the following URI: Bulk requests are identified using the following URI:
"urn:ietf:params:scim:api:messages:2.0:BulkRequest". Bulk responses "urn:ietf:params:scim:api:messages:2.0:BulkRequest". Bulk responses
are identified using the following URI: are identified using the following URI:
skipping to change at page 44, line 7 skipping to change at page 45, line 7
except in the event of a POST failure. except in the event of a POST failure.
response The HTTP response body to the specified request response The HTTP response body to the specified request
operation. When indicating a response with an HTTP status operation. When indicating a response with an HTTP status
other than a 200 series response, the response body MUST be other than a 200 series response, the response body MUST be
included. For normal completion, the server MAY elect to omit included. For normal completion, the server MAY elect to omit
the response body. the response body.
status The HTTP response status code to the requested operation. status The HTTP response status code to the requested operation.
When indicating an error, the "response" attribute MUST contain When indicating an error, the "response" attribute MUST contain
the detailed error response as per Section 3.10. the detailed error response as per Section 3.12.
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 client MAY override possible and disregard partial failures. The client MAY override
this behavior by specifying a value for the "failOnErrors" attribute. this behavior by specifying a value for the "failOnErrors" attribute.
The failOnErrors attribute defines the number of errors that the The failOnErrors attribute defines the number of errors that the
service provider should accept before failing the remaining service provider should accept before failing the remaining
operations returning the response. operations 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 MUST be specified when creating new resources. The "bulkId" is
defined by the client as a surrogate identifier in a POST operation defined by the client as a surrogate identifier in a POST operation
(see Section 3.5.2). The service provider MUST return the same (see Section 3.7.2). The service provider MUST return the same
"bulkId" together with the newly created resource. The "bulkId" can "bulkId" together with the newly created resource. The "bulkId" can
then be used by the client to map the service provider id with the then be used by the client to map the service provider id with the
"bulkId" of the created resource. "bulkId" of the created resource.
A SCIM service provider MAY elect to optimize a sequence operations A SCIM service provider MAY elect to optimize a sequence operations
received (e.g. to improve processing performance). When doing so, received (e.g. to improve processing performance). When doing so,
the service provider MUST ensure the clients intent is preserved and the service provider MUST ensure the clients intent is preserved and
the same stateful result is achieved as for non-optimized processing. the same stateful result is achieved as for non-optimized processing.
For example, before a "User" can be added to a "Group", they must For example, before a "User" can be added to a "Group", they must
first be created. Processing these requests out of order, might first be created. Processing these requests out of order, might
result in a failure to add the new "User" to the "Group". result in a failure to add the new "User" to the "Group".
3.5.1. Circular Reference Processing 3.7.1. Circular Reference Processing
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 /v2/Bulk POST /v2/Bulk
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
skipping to change at page 47, line 14 skipping to change at page 48, line 14
"value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"$ref": "$ref":
"https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"type": "Group" "type": "Group"
} }
] ]
} }
] ]
} }
3.5.2. BulkdId Temporary Identifiers 3.7.2. BulkdId Temporary Identifiers
A SCIM client can, within one bulk operation, create a new "User", a A SCIM client can, within one bulk operation, create a new "User", a
new "Group" and add the newly created "User" to the newly created new "Group" and add the newly created "User" to the newly created
"Group". In order to add the new "User" to the "Group" the client "Group". In order to add the new "User" to the "Group" the client
must use the surrogate id attribute, "bulkId", to reference the User. must use the surrogate id attribute, "bulkId", to reference the User.
The "bulkId" attribute value must be pre-pended with the literal The "bulkId" attribute value must be pre-pended with the literal
"bulkId:"; e.g., if the bulkId is 'qwerty', the value is "bulkId:"; e.g., if the bulkId is 'qwerty', the value is
"bulkId:qwerty". The service provider MUST replace the string "bulkId:qwerty". The service provider MUST replace the string
"bulkId:qwerty" with the permanent resource id once created. "bulkId:qwerty" with the permanent resource id once created.
skipping to change at page 51, line 46 skipping to change at page 52, line 46
"manager": { "manager": {
"managerId": "batchId:qwerty", "managerId": "batchId:qwerty",
"displayName": "Alice" "displayName": "Alice"
} }
} }
} }
} }
] ]
} }
3.5.3. Response and Error Handling 3.7.3. Response and Error Handling
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 endpoint MUST be returned for all operations excluding resource's endpoint 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
skipping to change at page 57, line 29 skipping to change at page 58, line 29
"location": "location":
"https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"method": "POST", "method": "POST",
"bulkId": "ytrewq", "bulkId": "ytrewq",
"version": "W\/\"lha5bbazU3fNvfe5\"", "version": "W\/\"lha5bbazU3fNvfe5\"",
"status": "201" "status": "201"
} }
] ]
} }
3.5.4. Maximum Operations 3.7.4. Maximum Operations
The service provider MUST define the maximum number of operations and The service provider MUST define the maximum number of operations and
maximum payload size a client may send in a single request. These maximum payload size a client may send in a single request. These
limits MAY be retrieved from the Service Provider Configuration (see limits MAY be retrieved from the Service Provider Configuration (see
'bulk' in Section 8 of [I-D.ietf-scim-core-schema]). If either 'bulk' in Section 8 of [I-D.ietf-scim-core-schema]). If either
limits are exceeded the service provider MUST return the HTTP 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 client sent a request exceeding the service The following example the client sent a request exceeding the service
skipping to change at page 58, line 18 skipping to change at page 59, line 18
HTTP/1.1 413 Request Entity Too Large HTTP/1.1 413 Request Entity Too Large
Content-Type: application/scim+json Content-Type: application/scim+json
{ {
"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"], "schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],
"status": "413", "status": "413",
"detail": "detail":
"The size of the bulk operation exceeds the maxPayloadSize (1048576)." "The size of the bulk operation exceeds the maxPayloadSize (1048576)."
} }
3.6. Data Input/Output Formats 3.8. Data Input/Output Formats
Servers MUST accept requests and respond with JSON structured Servers MUST accept requests and respond with JSON structured
responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default
encoding format. encoding format.
Clients using other encodings MUST specify the format in which the Clients using other encodings MUST specify the format in which the
data is submitted via HTTP header "Content-Type" as specified in data is submitted via HTTP header "Content-Type" as specified in
Section 3.1.1.5 [RFC7231] and MAY specify the desired response data Section 3.1.1.5 [RFC7231] and MAY specify the desired response data
format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g., format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g.,
"Accept: application/scim+json" or via URI suffix; e.g., "Accept: application/scim+json" or via URI suffix; e.g.,
skipping to change at page 59, line 5 skipping to change at page 60, line 5
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 Operation Response Parameters 3.9. Additional Operation Response Parameters
For any SCIM operation where a resource representation is returned For any SCIM operation where a resource representation is returned
(e.g. HTTP GET), the attributes returned are defined as the minimum (e.g. HTTP GET), the attributes returned are defined as the minimum
attribute set plus default attributes set. The minimum set are those attribute set plus default attributes set. The minimum set are those
attributes whose schema have "returned" set to "always". The default attributes whose schema have "returned" set to "always". The default
attribute set are those attributes whose schema have "returned" set attribute set are those attributes whose schema have "returned" set
to "default". to "default".
Clients 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
either of the mutually exclusive URL query parameters "attributes" OR either of the mutually exclusive URL query parameters "attributes" OR
"excludedAtributes" as follows: "excludedAtributes" as follows:
attributes When specified the default list of attributes SHALL be attributes When specified the default list of attributes SHALL be
overridden and each resource returned MUST contain the overridden and each resource returned MUST contain the
minimum set of resource attributes and any attributes or sub- minimum set of resource attributes and any attributes or sub-
attributes explicitly requested by the "attributes" attributes explicitly requested by the "attributes"
parameter. The query parameter attributes value is a comma parameter. The query parameter attributes value is a comma
separated list of resource attribute names in standard separated list of resource attribute names in standard
attribute notation (Section 3.8) form (e.g. userName, name, attribute notation (Section 3.10) form (e.g. userName, name,
emails). emails).
excludedAttributes When specified, each resource returned MUST excludedAttributes When specified, each resource returned MUST
contain the minimal set of resource attributes. contain the minimal set of resource attributes.
Additionally, the default set of attributes minus those Additionally, the default set of attributes minus those
attributes listed in "excludedAttributes" are also returned. attributes listed in "excludedAttributes" are also returned.
The query parameter attributes value is a comma separated The query parameter attributes value is a comma separated
list of resource attribute names in standard attribute list of resource attribute names in standard attribute
notation (Section 3.8) form (e.g. userName, name, emails). notation (Section 3.10) 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/scim+json Accept: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Giving the response Giving the response
HTTP/1.1 200 OK HTTP/1.1 200 OK
skipping to change at page 60, line 24 skipping to change at page 61, line 24
"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": "location":
"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"a330bc54f0671c9\"" "version":"W\/\"a330bc54f0671c9\""
} }
} }
3.8. Attribute Notation 3.10. 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:ietf:params:scim:schemas:core:2.0:User:userName". identified as "urn:ietf:params:scim:schemas:core:2.0:User:userName".
Clients MAY omit core schema attribute URN prefixes though MUST fully Clients MAY omit core schema attribute URN prefixes though MUST fully
qualify extended attributes with the associated resource URN; e.g., qualify extended attributes with the associated resource URN; e.g.,
the attribute 'age' defined in the attribute 'age' defined in
"urn:ietf:params:scim:schemas:exampleCo:2.0:hr" is fully encoded as "urn:ietf:params:scim:schemas:exampleCo:2.0:hr" is fully encoded as
"urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age". A Complex "urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age". A Complex
attributes' Sub-Attributes are referenced via nested, dot ('.') attributes' Sub-Attributes are referenced via nested, dot ('.')
notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For
example, the fully qualified path for a User's givenName is example, the fully qualified path for a User's givenName is
"urn:ietf:params:scim:schemas:core:2.0:User:name.givenName" All "urn:ietf:params:scim:schemas:core:2.0:User:name.givenName" All
facets (URN, attribute and Sub-Attribute name) of the fully encoded facets (URN, attribute and Sub-Attribute name) of the fully encoded
Attribute name are case insensitive. Attribute name are case insensitive.
3.9. "/Me" Authenticated Subject Alias 3.11. "/Me" Authenticated Subject Alias
A client MAY use a URL of the form "<base-URI>/Me" as a URI alias for A client MAY use a URL of the form "<base-URI>/Me" as a URI alias for
the User or other resource associated with the currently the User or other resource associated with the currently
authenticated subject for any SCIM operation. A service provider MAY authenticated subject for any SCIM operation. A service provider MAY
respond in ONE of 3 ways: respond in ONE of 3 ways:
o A service provider that does NOT support this feature SHOULD o A service provider that does NOT support this feature SHOULD
respond with status 403 (FORBIDDEN). respond with status 403 (FORBIDDEN).
o A service provider MAY choose to redirect the client using HTTP o A service provider MAY choose to redirect the client using HTTP
skipping to change at page 61, line 25 skipping to change at page 62, line 25
location of the aliased resource associated with the authenticated location of the aliased resource associated with the authenticated
subject. subject.
When using the SCIM Create Resource command (HTTP POST) with the When using the SCIM Create Resource command (HTTP POST) with the
"/Me" alias, the desired resourceType being created is at the "/Me" alias, the desired resourceType being created is at the
discretion of the service provider based on the authenticated subject discretion of the service provider based on the authenticated subject
(if not anonymous) making the request and any request body attributes (if not anonymous) making the request and any request body attributes
(e.g. "schemas"). See Section 7.3 for information on security (e.g. "schemas"). See Section 7.3 for information on security
considerations related to this operation. considerations related to this operation.
3.10. HTTP Status and Error Response Handling 3.12. HTTP Status and Error Response Handling
The SCIM Protocol uses the HTTP status response status codes defined The SCIM Protocol uses the HTTP status response status codes defined
in Section 6 [RFC7231] to indicate operation success or failure. In in Section 6 [RFC7231] to indicate operation success or failure. In
addition to returning a HTTP response code implementers MUST return addition to returning a HTTP response code implementers MUST return
the errors in the body of the response in the client requested format the errors in the body of the response in the client requested format
containing the error response and, per the HTTP specification, human- containing the error response and, per the HTTP specification, human-
readable explanations. Error responses are identified using the readable explanations. Error responses are identified using the
following "schema" URI: following "schema" URI:
"urn:ietf:params:scim:api:messages:2.0:Error". The following "urn:ietf:params:scim:api:messages:2.0:Error". The following
attributes are defined for a SCIM error response using a JSON body: attributes are defined for a SCIM error response using a JSON body:
skipping to change at page 63, line 11 skipping to change at page 64, line 11
+--------------+---------------+------------------------------------+ +--------------+---------------+------------------------------------+
Table 7: SCIM HTTP Status Code Usage Table 7: SCIM HTTP Status Code Usage
For HTTP Status 400 (Bad Request) responses, the following detail For HTTP Status 400 (Bad Request) responses, the following detail
error types are defined: error types are defined:
+--------------+------------------------------+---------------------+ +--------------+------------------------------+---------------------+
| scimType | Description | Applicability | | scimType | Description | Applicability |
+--------------+------------------------------+---------------------+ +--------------+------------------------------+---------------------+
| invalidFilte | The specified filter syntax | GET(Section 3.2.2), | | invalidFilte | The specified filter syntax | GET(Section 3.4.2), |
| r | was invalid (does not comply | POST (Search - | | r | was invalid (does not comply | POST (Search - |
| | with Figure 1) or the | Section 3.2.3), | | | with Figure 1) or the | Section 3.4.3), |
| | specified attribute and | PATCH (Path Filter | | | specified attribute and | PATCH (Path Filter |
| | filter comparison | - Section 3.3.2) | | | filter comparison | - Section 3.5.2) |
| | combination is not | | | | combination is not | |
| | supported. | | | | supported. | |
| tooMany | The specified filter yields | GET(Section 3.2.2), | | tooMany | The specified filter yields | GET(Section 3.4.2), |
| | many more results than the | POST (Search - | | | many more results than the | POST (Search - |
| | server is willing calculate | Section 3.2.3) | | | server is willing calculate | Section 3.4.3) |
| | or process. For example, a | | | | or process. For example, a | |
| | filter such as "(userName | | | | filter such as "(userName | |
| | pr)" by itself would return | | | | pr)" by itself would return | |
| | all entries with a | | | | all entries with a | |
| | "userName" and MAY not be | | | | "userName" and MAY not be | |
| | acceptable to the service | | | | acceptable to the service | |
| | provider. | | | | provider. | |
| uniqueness | One or more of attribute | POST (Create - | | uniqueness | One or more of attribute | POST (Create - |
| | values is already in use or | Section 3.1), PUT | | | values is already in use or | Section 3.3), PUT |
| | is reserved. | (Section 3.3.1), | | | is reserved. | (Section 3.5.1), |
| | | PATCH (Section | | | | PATCH (Section |
| | | 3.3.2) | | | | 3.5.2) |
| mutability | The attempted modification | PUT (Section | | mutability | The attempted modification | PUT (Section |
| | is not compatible with the | 3.3.1), PATCH | | | is not compatible with the | 3.5.1), PATCH |
| | target attributes mutability | (Section 3.3.2) | | | target attributes mutability | (Section 3.5.2) |
| | or current state (e.g. | | | | or current state (e.g. | |
| | modification of an immutable | | | | modification of an immutable | |
| | attribute with an existing | | | | attribute with an existing | |
| | value). | | | | value). | |
| invalidSynta | The request body message | POST (Search - | | invalidSynta | The request body message | POST (Search - |
| x | structure was invalid or did | Section 3.2.2, | | x | structure was invalid or did | Section 3.4.2, |
| | not conform to the request | Create - Section | | | not conform to the request | Create - Section |
| | schema. | 3.1, Bulk - Section | | | schema. | 3.3, Bulk - Section |
| | | 3.5), PUT (Section | | | | 3.7), PUT (Section |
| | | 3.3.1) | | | | 3.5.1) |
| invalidPath | The path attribute was | PATCH (Section | | invalidPath | The path attribute was | PATCH (Section |
| | invalid or malformed (see | 3.3.2) | | | invalid or malformed (see | 3.5.2) |
| | Figure 7). | | | | Figure 7). | |
| noTarget | The specified "path" did not | PATCH (Section | | noTarget | The specified "path" did not | PATCH (Section |
| | yield an attribute or | 3.3.2) | | | yield an attribute or | 3.5.2) |
| | attribute value that could | | | | attribute value that could | |
| | be operated on. This occurs | | | | be operated on. This occurs | |
| | when the specified "path" | | | | when the specified "path" | |
| | value contains a filter that | | | | value contains a filter that | |
| | yields no match. | | | | yields no match. | |
| invalidValue | A required value was | GET (Section | | invalidValue | A required value was | GET (Section |
| | missing, or the value | 3.2.2), POST | | | missing, or the value | 3.4.2), POST |
| | specified was not compatible | (Create - Section | | | specified was not compatible | (Create - Section |
| | with the operation or | 3.1, Query - | | | with the operation or | 3.3, Query - |
| | attribute type (see Section | Section 3.2.2), PUT | | | attribute type (see Section | Section 3.4.2), PUT |
| | 2.1 [I-D.ietf-scim-core-sche | (Section 3.3.1), | | | 2.1 [I-D.ietf-scim-core-sche | (Section 3.5.1), |
| | ma]), or schema (see Section | PATCH (Section | | | ma]), or schema (see Section | PATCH (Section |
| | 4 [I-D.ietf-scim-core-schema | 3.3.2) | | | 4 [I-D.ietf-scim-core-schema | 3.5.2) |
| | ]). | | | | ]). | |
| invalidVers | The specified SCIM protocol | GET (Section | | invalidVers | The specified SCIM protocol | GET (Section |
| | version is not supported | 3.2.2), POST (ALL), | | | version is not supported | 3.4.2), POST (ALL), |
| | (see Section 3.11). | PUT (Section | | | (see Section 3.13). | PUT (Section |
| | | 3.3.1), PATCH | | | | 3.5.1), PATCH |
| | | (Section 3.3.2), | | | | (Section 3.5.2), |
| | | DELETE (Section | | | | DELETE (Section |
| | | 3.4) | | | | 3.6) |
+--------------+------------------------------+---------------------+ +--------------+------------------------------+---------------------+
Table 8: Table of SCIM Detail Error Keyword Values Table 8: Table of SCIM Detail Error Keyword Values
Note that in the table above (Table 8), the applicability table Note that in the table above (Table 8), the applicability table
applies to the normal HTTP method but MAY apply within a SCIM Bulk applies to the normal HTTP method but MAY apply within a SCIM Bulk
operation (via HTTP POST). operation (via HTTP POST).
Error example in response to a non-existent GET request. Error example in response to a non-existent GET request.
skipping to change at page 65, line 13 skipping to change at page 66, line 13
} }
[[Editor's note: while the detail error codes seem to have consensus, [[Editor's note: while the detail error codes seem to have consensus,
there is a question about whether the error codes should be there is a question about whether the error codes should be
extensible so that individual service providers may define site extensible so that individual service providers may define site
specific codes. Should all scimTypes be URIs, so that scimTypes can specific codes. Should all scimTypes be URIs, so that scimTypes can
be registered via IANA? Should there be a separate field defined for be registered via IANA? Should there be a separate field defined for
this purpose? Or, should custom signalling (for non-protocol/schema this purpose? Or, should custom signalling (for non-protocol/schema
errors, be out of scope?]] errors, be out of scope?]]
3.11. API Versioning 3.13. 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 of this specification, the segment in the URL path. At this time of this specification, the
identifier is 'v2'. If specified, the version identifier MUST appear identifier is 'v2'. If specified, the version identifier MUST appear
in the URL path immediately preceding the resource endpoint and in the URL path immediately preceding the resource endpoint and
conform to the following scheme: the character 'v' followed by the conform to the following scheme: the character 'v' followed by the
desired SCIM version number; e.g., a version 'v2' User request is desired SCIM version number; e.g., a version 'v2' User request is
specified as /v2/Users. When specified service providers MUST specified as /v2/Users. When specified service providers MUST
perform the operation using the desired version or reject the perform the operation using the desired version or reject the
request. When omitted service providers SHOULD perform the operation request. When omitted service providers SHOULD perform the operation
using the most recent SCIM protocol version supported by the service using the most recent SCIM protocol version supported by the service
provider. provider.
3.12. Versioning Resources 3.14. Versioning Resources
The SCIM protocol supports resource versioning via standard HTTP The SCIM protocol supports resource versioning via standard HTTP
ETags Section 2.3 [RFC7233]. Service providers MAY support weak ETags Section 2.3 [RFC7233]. Service providers MAY support weak
ETags as the preferred mechanism for performing conditional ETags as the preferred mechanism for performing conditional
retrievals and ensuring clients do not inadvertently overwrite each retrievals and ensuring clients do not inadvertently overwrite each
others changes, respectively. When supported SCIM ETags MUST be others changes, respectively. When supported SCIM ETags MUST be
specified as an HTTP header and SHOULD be specified within the specified as an HTTP header and SHOULD be specified within the
'version' attribute contained in the resource's 'meta' attribute. 'version' attribute contained in the resource's 'meta' attribute.
Example: Example:
skipping to change at page 68, line 17 skipping to change at page 69, line 17
resources available on a SCIM Service Provider (e.g. Users and resources available on a SCIM Service Provider (e.g. Users and
Groups). Each resource type defines the endpoints, the core Groups). Each resource type defines the endpoints, the core
schema URI that defines the resource, and any supported schema schema URI that defines the resource, and any supported schema
extensions. The attributes defining a resource type can be found extensions. The attributes defining a resource type can be found
in Section 6 [I-D.ietf-scim-core-schema], and an example in Section 6 [I-D.ietf-scim-core-schema], and an example
representation can be found in Section 8.6 representation can be found in Section 8.6
[I-D.ietf-scim-core-schema]. [I-D.ietf-scim-core-schema].
In cases where a request is for a specific "ResourceType" or In cases where a request is for a specific "ResourceType" or
"Schema", the single JSON object is returned in the same way a single "Schema", the single JSON object is returned in the same way a single
User or Group is retrieved as per Section 3.2.1. When returning User or Group is retrieved as per Section 3.4.1. When returning
multiple ResourceTypes or Schemas, the message form described by multiple ResourceTypes or Schemas, the message form described by
"urn:ietf:params:scim:api:messages:2.0:ListResponse" (ListResponse) "urn:ietf:params:scim:api:messages:2.0:ListResponse" (ListResponse)
form SHALL be used as shown in Figure 3 and Figure 9 below. Query form SHALL be used as shown in Figure 3 and Figure 9 below. Query
parameters described in section 3.2 such as, sorting, attributes, and parameters described in section 3.2 such as, sorting, attributes, and
paging SHALL be ignored. If a "filter" is provided, the service paging SHALL be ignored. If a "filter" is provided, the service
provider SHOULD respond with HTTP Status 403 (FORBIDDEN) to ensure provider SHOULD respond with HTTP Status 403 (FORBIDDEN) to ensure
clients cannot incorrectly assume any matching conditions specified clients cannot incorrectly assume any matching conditions specified
in a filter are true. in a filter are true.
The following is a non-normative example of an HTTP GET to the The following is a non-normative example of an HTTP GET to the
skipping to change at page 72, line 22 skipping to change at page 73, line 22
As mentioned in ,Section 9.4 [RFC7231], SCIM clients requesting As mentioned in ,Section 9.4 [RFC7231], SCIM clients requesting
information using query filters using HTTP GET SHOULD give information using query filters using HTTP GET SHOULD give
consideration to the information content of the filters and whether consideration to the information content of the filters and whether
their exposure in a URI would represent a breach of security or their exposure in a URI would represent a breach of security or
confidentiality through leakage in a web browsers or server logs. confidentiality through leakage in a web browsers or server logs.
This is particularly true for information that is legally considered This is particularly true for information that is legally considered
"personally identifiable information" or is otherwise restricted by "personally identifiable information" or is otherwise restricted by
privacy laws. In these situations to ensure maximum security and privacy laws. In these situations to ensure maximum security and
confidentiality, clients SHOULD query using HTTP POST (see confidentiality, clients SHOULD query using HTTP POST (see
Section 3.2.3 ). Section 3.4.3 ).
Servers that receive HTTP GET requests using filters that contain Servers that receive HTTP GET requests using filters that contain
restricted or confidential information SHOULD respond with HTTP restricted or confidential information SHOULD respond with HTTP
status 403 indicating the operation is FORBIDDEN. A detailed error, status 403 indicating the operation is FORBIDDEN. A detailed error,
"confidential_restricted" may be returned indicating the request must "confidential_restricted" may be returned indicating the request must
be submitted using POST. A non-normative example: be submitted using POST. A non-normative example:
HTTP/1.1 403 FORBIDDEN HTTP/1.1 403 FORBIDDEN
{ {
skipping to change at page 76, line 9 skipping to change at page 77, line 9
the following registers and extends the SCIM Schema Registry to the following registers and extends the SCIM Schema Registry to
define SCIM protocol request/response JSON schema URN identifier define SCIM protocol request/response JSON schema URN identifier
prefix of "urn:ietf:params:scim:api:messages:2.0" which is part of prefix of "urn:ietf:params:scim:api:messages:2.0" which is part of
the URN sub-Namespace for SCIM. There is no specific associated the URN sub-Namespace for SCIM. There is no specific associated
resource type. resource type.
+---------------------------------+-----------------+---------------+ +---------------------------------+-----------------+---------------+
| Schema URI | Name | Reference | | Schema URI | Name | Reference |
+---------------------------------+-----------------+---------------+ +---------------------------------+-----------------+---------------+
| urn:ietf:params:scim:api: | List/Query | See Section | | urn:ietf:params:scim:api: | List/Query | See Section |
| messages:2.0:ListResponse | Response | 3.2.2 | | messages:2.0:ListResponse | Response | 3.4.2 |
| urn:ietf:params:scim:api: | POST Query | See Section | | urn:ietf:params:scim:api: | POST Query | See Section |
| messages:2.0:SearchRequest | Request | 3.2.3 | | messages:2.0:SearchRequest | Request | 3.4.3 |
| urn:ietf:params:scim:api: | Patch Operation | See Section | | urn:ietf:params:scim:api: | Patch Operation | See Section |
| messages:2.0:PatchOp | | 3.3.2 | | messages:2.0:PatchOp | | 3.5.2 |
| urn:ietf:params:scim:api: | Bulk Operations | See Section | | urn:ietf:params:scim:api: | Bulk Operations | See Section |
| messages:2.0:BulkRequest | Request | 3.5 | | messages:2.0:BulkRequest | Request | 3.7 |
| urn:ietf:params:scim:api: | Bulk Operations | See Section | | urn:ietf:params:scim:api: | Bulk Operations | See Section |
| messages:2.0:BulkResponse | Response | 3.5 | | messages:2.0:BulkResponse | Response | 3.7 |
| urn:ietf:params:scim:api: | Error Response | See Section | | urn:ietf:params:scim:api: | Error Response | See Section |
| messages:2.0:Error | | 3.10 | | messages:2.0:Error | | 3.12 |
+---------------------------------+-----------------+---------------+ +---------------------------------+-----------------+---------------+
Table 9: SCIM Schema URIs for Data Resources Table 9: SCIM Schema URIs for Data Resources
9. References 9. References
9.1. Normative References 9.1. Normative References
[I-D.ietf-precis-saslprepbis] [I-D.ietf-precis-saslprepbis]
Saint-Andre, P. and A. Melnikov, "Preparation, Saint-Andre, P. and A. Melnikov, "Preparation,
Enforcement, and Comparison of Internationalized Strings Enforcement, and Comparison of Internationalized Strings
Representing Usernames and Passwords", draft-ietf-precis- Representing Usernames and Passwords", draft-ietf-precis-
saslprepbis-13 (work in progress), December 2014. saslprepbis-14 (work in progress), March 2015.
[I-D.ietf-scim-core-schema] [I-D.ietf-scim-core-schema]
Hunt, P., Grizzle, K., Wahlstroem, E., and C. Mortimore, Hunt, P., Grizzle, K., Wahlstroem, E., and C. Mortimore,
"System for Cross-Domain Identity Management: Core "System for Cross-Domain Identity Management: Core
Schema", draft-ietf-scim-core-schema-16 (work in Schema", draft-ietf-scim-core-schema-17 (work in
progress), February 2015. progress), March 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, November 2003.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005. 3986, January 2005.
skipping to change at page 77, line 34 skipping to change at page 78, line 34
[RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Authentication", RFC 7235, June 2014. (HTTP/1.1): Authentication", RFC 7235, June 2014.
9.2. Informative References 9.2. Informative References
[I-D.ietf-precis-framework] [I-D.ietf-precis-framework]
Saint-Andre, P. and M. Blanchet, "PRECIS Framework: Saint-Andre, P. and M. Blanchet, "PRECIS Framework:
Preparation, Enforcement, and Comparison of Preparation, Enforcement, and Comparison of
Internationalized Strings in Application Protocols", Internationalized Strings in Application Protocols",
draft-ietf-precis-framework-22 (work in progress), draft-ietf-precis-framework-23 (work in progress),
February 2015. February 2015.
[OpenSearch] [OpenSearch]
Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . Clinton, D., "OpenSearch Protocol 1.1, Draft 5", .
[Order-Operations] [Order-Operations]
Wikipedia, "Order of Operations: Programming Languages", . Wikipedia, "Order of Operations: Programming Languages", .
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
6749, October 2012. 6749, October 2012.
skipping to change at page 78, line 11 skipping to change at page 79, line 11
[RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819, Threat Model and Security Considerations", RFC 6819,
January 2013. January 2013.
[RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation
(JSON) Patch", RFC 6902, April 2013. (JSON) Patch", RFC 6902, April 2013.
[RFC7238] Reschke, J., "The Hypertext Transfer Protocol Status Code [RFC7238] Reschke, J., "The Hypertext Transfer Protocol Status Code
308 (Permanent Redirect)", RFC 7238, June 2014. 308 (Permanent Redirect)", RFC 7238, June 2014.
[XML-Schema]
Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes
Second Edition", October 2004.
Appendix A. Contributors Appendix A. Contributors
Samuel Erdtman (samuel@erdtman.se) Samuel Erdtman (samuel@erdtman.se)
Patrick Harding (pharding@pingidentity.com) Patrick Harding (pharding@pingidentity.com)
Appendix B. Acknowledgments Appendix B. Acknowledgments
The editors would like to acknowledge the contribution and work of The editors would like to acknowledge the contribution and work of
the past draft editors: the past draft editors:
skipping to change at page 82, line 29 skipping to change at page 83, line 34
be returned per the response example in figure 4. be returned per the response example in figure 4.
Clarifications and improvements to examples in PATCH replace Clarifications and improvements to examples in PATCH replace
operations operations
Updated references to saslprep and precis frameworks Updated references to saslprep and precis frameworks
Draft 15 - PH - Clarifications on returning "path" handling during Draft 15 - PH - Clarifications on returning "path" handling during
PATCH "replace" operations. Updated references. PATCH "replace" operations. Updated references.
Draft 16 - PH - Clarification of SCIM protocol definitions of
resources vs messages and general process rules regarding schema
including validation.
Authors' Addresses Authors' Addresses
Phil Hunt (editor) Phil Hunt (editor)
Oracle Corporation Oracle Corporation
Email: phil.hunt@yahoo.com Email: phil.hunt@yahoo.com
Kelly Grizzle Kelly Grizzle
SailPoint SailPoint
 End of changes. 100 change blocks. 
168 lines changed or deleted 239 lines changed or added

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