draft-ietf-scim-api-16.txt   draft-ietf-scim-api-17.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: September 9, 2015 SailPoint Expires: October 26, 2015 SailPoint
M. Ansari M. Ansari
Cisco Cisco
E. Wahlstroem E. Wahlstroem
Nexus Technology Nexus Technology
C. Mortimore C. Mortimore
Salesforce Salesforce
March 8, 2015 April 24, 2015
System for Cross-Domain Identity Management: Protocol System for Cross-Domain Identity Management: Protocol
draft-ietf-scim-api-16 draft-ietf-scim-api-17
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 service.
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
integration, while applying existing authentication, authorization, integration, while applying existing authentication, authorization,
and privacy models. SCIM's intent is to reduce the cost and and privacy models. SCIM's intent is to reduce the cost and
complexity of user management operations by providing a common user complexity of user management operations by providing a common user
schema and extension model and a service protocol defined by this schema, an extension model, and a service protocol defined by this
document. document.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 9, 2015. This Internet-Draft will expire on October 26, 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 3, line 14 skipping to change at page 3, line 14
5. Preparation and Comparison of Internationalized Strings . . . 70 5. Preparation and Comparison of Internationalized Strings . . . 70
6. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 71 6. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 71
6.1. Associating Clients to Tenants . . . . . . . . . . . . . 71 6.1. Associating Clients to Tenants . . . . . . . . . . . . . 71
6.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 72 6.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 72
7. Security Considerations . . . . . . . . . . . . . . . . . . . 72 7. Security Considerations . . . . . . . . . . . . . . . . . . . 72
7.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 72 7.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 72
7.2. Disclosure of Sensitive Information in URIs . . . . . . . 73 7.2. Disclosure of Sensitive Information in URIs . . . . . . . 73
7.3. Anonymous Requests . . . . . . . . . . . . . . . . . . . 73 7.3. Anonymous Requests . . . . . . . . . . . . . . . . . . . 73
7.4. HTTP Considerations . . . . . . . . . . . . . . . . . . . 74 7.4. HTTP Considerations . . . . . . . . . . . . . . . . . . . 74
7.5. Secure Storage and Handling of Sensitive Data . . . . . . 74 7.5. Secure Storage and Handling of Sensitive Data . . . . . . 74
7.6. Case Insensitive Comparision & International Languages . 75 7.6. Case Insensitive Comparison & International Languages . . 75
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 75 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 75
8.1. Media Type Registration . . . . . . . . . . . . . . . . . 75 8.1. Media Type Registration . . . . . . . . . . . . . . . . . 75
8.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 76 8.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 76
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 77 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 77
9.1. Normative References . . . . . . . . . . . . . . . . . . 77 9.1. Normative References . . . . . . . . . . . . . . . . . . 77
9.2. Informative References . . . . . . . . . . . . . . . . . 78 9.2. Informative References . . . . . . . . . . . . . . . . . 78
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 79 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 79
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 79 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 79
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 79 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 79
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 83 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.
The definition of resources, attributes, and overall schema are
defined in the SCIM Core Schema document (see
[I-D.ietf-scim-core-schema]). [[RFC Editor: These specifications
should be published together]]
1.1. Intended Audience 1.1. Intended Audience
This document is intended as a guide to SCIM protocol usage for both This document is intended as a guide to SCIM protocol usage for both
SCIM HTTP service providers and HTTP clients who may provision SCIM HTTP service providers and HTTP clients who may provision
information to service providers or retrieve information from them. information to service providers or retrieve information from them.
1.2. Notational Conventions 1.2. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
skipping to change at page 4, line 16 skipping to change at page 4, line 20
Implementers MUST percent encode URLs as described in Section 2.1 of Implementers MUST percent encode URLs as described in Section 2.1 of
[RFC3986]. [RFC3986].
Throughout this documents all figures MAY contain spaces and extra Throughout this documents all figures MAY contain spaces and extra
line-wrapping for readability and space limitations. Similarly, some line-wrapping for readability and space limitations. Similarly, some
URI's contained within examples, have been shortened for space and URI's contained within examples, have been shortened for space and
readability reasons. readability reasons.
1.3. Definitions 1.3. Definitions
This specification uses the definitions from
[I-D.ietf-scim-core-schema], and defines the following additional
terms:
Base URI Base URI
The SCIM HTTP protocol is described in terms of a path relative to The SCIM HTTP protocol is described in terms of a path relative to
a Base URI. The Base URI MUST NOT contain a query string as a Base URI. The Base URI MUST NOT contain a query string as
clients may append additional path information and query clients MAY append additional path information and query
parameters as part of forming the request. The base URI most parameters as part of forming the request. The base URI most
often is a URL which most often consists of the "https" protocol often is a URL which most often consists of the "https" protocol
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.13 ). 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
skipping to change at page 5, line 27 skipping to change at page 5, line 34
SCIM is a protocol that is based on HTTP protocol [RFC7230]. Along SCIM is a protocol that is based on HTTP protocol [RFC7230]. Along
with HTTP headers and URIs, SCIM uses JSON [RFC7159] payloads to with HTTP headers and URIs, SCIM uses JSON [RFC7159] payloads to
convey both SCIM resources, as well as protocol specific payload convey both SCIM resources, as well as protocol specific payload
messages that convey request parameters and response information such messages that convey request parameters and response information such
as errors. Both resources and messages are passed in the form of as errors. Both resources and messages are passed in the form of
JSON based structures in the message body of an HTTP request or JSON based structures in the message body of an HTTP request or
response. To identify this content, SCIM uses a media type of response. To identify this content, SCIM uses a media type of
"application/scim+json" (see Section 8.1). "application/scim+json" (see Section 8.1).
A SCIM "resource" is a JSON object that may be created, maintained, A SCIM "resource" is a JSON object that MAY be created, maintained,
and retrieved through HTTP request methods as described in this and retrieved through HTTP request methods as described in this
document. Each JSON resource representation contains a "schemas" document. Each JSON resource representation contains a "schemas"
attribute that contains a list of one or more URIs that indicate attribute that contains a list of one or more URIs that indicate
included SCIM schemas that are used to indicate the attributes included SCIM schemas that are used to indicate the attributes
contained within a resource. Specific information about what contained within a resource. Specific information about what
attributes are defined within a schema MAY be obtained by querying a attributes are defined within a schema MAY be obtained by querying a
SCIM service provider's "/Schemas" endpoint for a schema definition SCIM service provider's "/Schemas" endpoint for a schema definition
(see Section 8.7 [I-D.ietf-scim-core-schema]). Responses from this (see Section 8.7 [I-D.ietf-scim-core-schema]). Responses from this
endpoint describe how a service provider supports a schema and in endpoint describe how a service provider supports a schema and in
particular how attribute qualities such as cardinality, case- particular how attribute qualities such as cardinality, case-
exactness, mutability, uniqueness, returnability, and whether an exactness, mutability, uniqueness, returnability, and whether an
attribute is required. While SCIM schemas and associated extension attribute is required. While SCIM schemas and associated extension
model are defined in [I-D.ietf-scim-core-schema], SCIM clients should model are defined in [I-D.ietf-scim-core-schema], SCIM clients should
expect that some attribute schema MAY change from service provider to expect that some attribute schema MAY change from service provider to
service provider, particularly across administrative domains. In service provider, particularly across administrative domains. In
cases where SCIM may be used as an open protocol in front of an cases where SCIM MAY be used as an open protocol in front of an
application service, it is quite reasonable to expect that some application service, it is quite reasonable to expect that some
service providers MAY only support a sub-set of the schema defined in service providers MAY only support a sub-set of the schema defined in
[I-D.ietf-scim-core-schema]. [I-D.ietf-scim-core-schema].
A SCIM message conveys protocol parameters about a SCIM request or A SCIM message conveys protocol parameters about a SCIM request or
response that are defined by this specification. As with a SCIM response that are defined by this specification. As with a SCIM
resource, a SCIM message is a JSON object that contains a "schemas" resource, a SCIM message is a JSON object that contains a "schemas"
attribute with a URI whose namespace prefix that MUST begin with attribute with a URI whose namespace prefix that MUST begin with
"urn:ietf:params:scim:api:". As SCIM protocol messages are fixed and "urn:ietf:params:scim:api:". As SCIM protocol messages are fixed and
defined by SCIM specifications and registered extensions, SCIM defined by SCIM specifications and registered extensions, SCIM
message schemas using the above prefix URN SHALL NOT be discoverable message schemas using the above prefix URN SHALL NOT be discoverable
using the "/Schemas" endpoint. using the "/Schemas" endpoint.
As SCIM is intended for use within cross-domain environments where As SCIM is intended for use within cross-domain environments where
schema and implementations MAY vary, techniques such as document schema and implementations MAY vary, techniques such as document
validation, such as in [XML-Schema], are not recommended. A SCIM validation, such as in [XML-Schema], are not recommended. A SCIM
service provider interprets a request in the context of its own service provider interprets a request in the context of its own
schema (which may be different from the client's schema) and schema (which MAY be different from the client's schema) and
following the defined processing rules for each request. The following the defined processing rules for each request. The
following sections in this document define the processing rules for following sections in this document define the processing rules for
SCIM and provide allowances for schema differences where appropriate. SCIM and provide allowances for schema differences where appropriate.
For example, in a SCIM PUT request, "readOnly" attributes are For example, in a SCIM PUT request, "readOnly" attributes are
ignored, while "readWrite" attributes are updated. There is no need ignored, while "readWrite" attributes are updated. There is no need
for a SCIM client to discover which attributes are "readOnly" and 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 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 to be accepted. Similarly a SCIM client SHOULD NOT expect a service
provider to return SCIM resources with exactly the same schema and provider to return SCIM resources with exactly the same schema and
values as submitted. SCIM responses SHALL reflect resource state as values as submitted. SCIM responses SHALL reflect resource state as
skipping to change at page 6, line 43 skipping to change at page 6, line 50
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.
GET GET
Retrieves one or more complete or partial resources. Retrieves one or more complete or partial resources.
POST POST
Depending on the endpoint, creates new resources, create a search Depending on the endpoint, creates new resources, create a search
request, or may be used to bulk modify resources. request, or MAY be used to bulk modify resources.
PUT PUT
Modifies a resource by replacing existing attributes with a Modifies a resource by replacing existing attributes with a
specified set of replacement attributes (replace). PUT MUST NOT specified set of replacement attributes (replace). PUT MUST NOT
be used to create new resources. be used to create new resources.
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).
skipping to change at page 7, line 26 skipping to change at page 7, line 33
DELETE (Section 3.6) DELETE (Section 3.6)
Group /Groups GET (Section 3.4.1), Retrieve, Add, Group /Groups GET (Section 3.4.1), Retrieve, Add,
POST (Section 3.3), Modify Groups POST (Section 3.3), Modify Groups
PUT (Section 3.5.1), PUT (Section 3.5.1),
PATCH (Section 3.5.2), PATCH (Section 3.5.2),
DELETE (Section 3.6) 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.11) 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.7) 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.4.3) Search from system Search [prefix]/.search POST (Section 3.4.3) Search from system
skipping to change at page 11, line 48 skipping to change at page 11, line 48
"type":"work" "type":"work"
} }
] ]
} }
3.4.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 SHALL NOT be equal to the number of
in the resources attribute of the list response if pagination elements in the resources attribute of the list response if
(Section 3.4.2.4) is requested. REQUIRED. pagination (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.4.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.
skipping to change at page 13, line 24 skipping to change at page 13, line 24
"/Groups" "/Groups"
A query against a server root indicates that ALL resources within the A query against a server root indicates that ALL resources within the
server SHALL be included subject to filtering. A filter expression server SHALL be included subject to filtering. A filter expression
using "meta.resourceType" MAY be used to restrict results to one or using "meta.resourceType" MAY be used to restrict results to one or
more specific resource types (to exclude others). For example: more specific resource types (to exclude others). For example:
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.4.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.4.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
skipping to change at page 15, line 5 skipping to change at page 15, line 5
| | than | operator value, there is a match. The | | | than | operator value, there is a match. The |
| | | actual comparison is dependent on the | | | | actual comparison is dependent on the |
| | | attribute type. For string attribute | | | | attribute type. For string attribute |
| | | types, this is a lexicographical | | | | types, this is a lexicographical |
| | | comparison and for DateTime types, it is | | | | comparison and for DateTime types, it is |
| | | a chronological comparison. For Integer | | | | a chronological comparison. For Integer |
| | | attributes it is a comparison by numeric | | | | attributes it is a comparison by numeric |
| | | value. Boolean and Binary attributes | | | | value. Boolean and Binary attributes |
| | | SHALL cause a failed response (HTTP | | | | SHALL cause a failed response (HTTP |
| | | Status 400) with scimType of | | | | Status 400) with scimType of |
| | | invlaidFiler. | | | | invalidFilter. |
| ge | greater | If the attribute value is greater than | | ge | greater | If the attribute value is greater than |
| | than or | or equal to the operator value, there is | | | than or | or equal to the operator value, there is |
| | equal | a match. The actual comparison is | | | equal | a match. The actual comparison is |
| | | dependent on the attribute type. For | | | | dependent on the attribute type. For |
| | | string attribute types, this is a | | | | string attribute types, this is a |
| | | lexicographical comparison and for | | | | lexicographical comparison and for |
| | | DateTime types, it is a chronological | | | | DateTime types, it is a chronological |
| | | comparison. For Integer attributes it is | | | | comparison. For Integer attributes it is |
| | | a comparison by numeric value. Boolean | | | | a comparison by numeric value. Boolean |
| | | and Binary attributes SHALL cause a | | | | and Binary attributes SHALL cause a |
| | | failed response (HTTP Status 400) with | | | | failed response (HTTP Status 400) with |
| | | scimType of invlaidFiler. | | | | scimType of invalidFilter. |
| lt | less than | If the attribute value is less than | | lt | less than | If the attribute value is less than |
| | | operator value, there is a match. The | | | | operator value, there is a match. The |
| | | actual comparison is dependent on the | | | | actual comparison is dependent on the |
| | | attribute type. For string attribute | | | | attribute type. For string attribute |
| | | types, this is a lexicographical | | | | types, this is a lexicographical |
| | | comparison and for DateTime types, it is | | | | comparison and for DateTime types, it is |
| | | a chronological comparison. For Integer | | | | a chronological comparison. For Integer |
| | | attributes it is a comparison by numeric | | | | attributes it is a comparison by numeric |
| | | value. Boolean and Binary attributes | | | | value. Boolean and Binary attributes |
| | | SHALL cause a failed response (HTTP | | | | SHALL cause a failed response (HTTP |
| | | Status 400) with scimType of | | | | Status 400) with scimType of |
| | | invlaidFiler. | | | | invalidFilter. |
| le | less than | If the attribute value is less than or | | le | less than | If the attribute value is less than or |
| | or equal | equal to the operator value, there is a | | | or equal | equal to the operator value, there is a |
| | | match. The actual comparison is | | | | match. The actual comparison is |
| | | dependent on the attribute type. For | | | | dependent on the attribute type. For |
| | | string attribute types, this is a | | | | string attribute types, this is a |
| | | lexicographical comparison and for | | | | lexicographical comparison and for |
| | | DateTime types, it is a chronological | | | | DateTime types, it is a chronological |
| | | comparison. For Integer attributes it is | | | | comparison. For Integer attributes it is |
| | | a comparison by numeric value. Boolean | | | | a comparison by numeric value. Boolean |
| | | and Binary attributes SHALL cause a | | | | and Binary attributes SHALL cause a |
| | | failed response (HTTP Status 400) with | | | | failed response (HTTP Status 400) with |
| | | scimType of invlaidFiler. | | | | scimType of invalidFilter. |
+----------+-------------+------------------------------------------+ +----------+-------------+------------------------------------------+
Table 2: Attribute Operators Table 2: Attribute Operators
+----------+-------------+------------------------------------------+ +----------+-------------+------------------------------------------+
| Operator | Description | Behavior | | Operator | Description | Behavior |
+----------+-------------+------------------------------------------+ +----------+-------------+------------------------------------------+
| and | Logical And | The filter is only a match if both | | and | Logical And | The filter is only a match if both |
| | | expressions evaluate to true. | | | | expressions evaluate to true. |
| or | Logical or | The filter is a match if either | | or | Logical or | The filter is a match if either |
| | | expression evaluates to true. | | | | expression evaluates to true. |
| not | Not | The filter is a match if the expression | | not | Not | The filter is a match if the expression |
| | function | evaluates to false. | | | function | evaluates to false. |
+----------+-------------+------------------------------------------+ +----------+-------------+------------------------------------------+
Table 3: Logical Operators Table 3: Logical Operators
+----------+-------------+------------------------------------------+ +----------+-------------+------------------------------------------+
| Operator | Description | Behavior | | Operator | Description | Behavior |
+----------+-------------+------------------------------------------+ +----------+-------------+------------------------------------------+
| ( ) | Precedence | Boolean expressions may be grouped using | | ( ) | Precedence | Boolean expressions MAY be grouped using |
| | grouping | parentheses to change the standard order | | | grouping | parentheses to change the standard order |
| | | of operations; i.e., evaluate OR logical | | | | of operations; i.e., evaluate "or" |
| | | operators before logical AND operators. | | | | logical operators before logical "and" |
| | | operators. |
| [ ] | Complex | Service providers MAY support complex | | [ ] | Complex | Service providers MAY support complex |
| | attribute | filters where expressions MUST be | | | attribute | filters where expressions MUST be |
| | filter | applied to the same value of a parent | | | filter | applied to the same value of a parent |
| | grouping | attribute specified immediately before | | | grouping | attribute specified immediately before |
| | | the left square bracket ("["). The | | | | the left square bracket ("["). The |
| | | expression within square brackets ("[" | | | | expression within square brackets ("[" |
| | | and "]") MUST be a valid filter | | | | and "]") MUST be a valid filter |
| | | expression based upon sub-attributes of | | | | expression based upon sub-attributes of |
| | | the parent attribute. Nested expressions | | | | the parent attribute. Nested expressions |
| | | MAY be used. See examples below. | | | | MAY be used. See examples below. |
skipping to change at page 18, line 4 skipping to change at page 18, line 4
"DIGIT" and "ALPHA" are defined per Appendix B.1 of [RFC5234] and, "DIGIT" and "ALPHA" are defined per Appendix B.1 of [RFC5234] and,
"URI" is defined per Appendix A of [RFC3986]. "URI" is defined per Appendix A of [RFC3986].
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.10). 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
skipping to change at page 19, line 5 skipping to change at page 19, line 5
String type attributes are case insensitive by default unless the String type attributes are case insensitive by default unless the
attribute type is defined as case exact. Attribute comparison attribute type is defined as case exact. Attribute comparison
operators 'eq', 'co', and 'sw' MUST perform caseIgnore matching for operators 'eq', 'co', and 'sw' MUST perform caseIgnore matching for
all string attributes unless the attribute is defined as case exact. all string attributes unless the attribute is defined as case exact.
By default all string attributes are case insensitive. By default all string attributes are case insensitive.
Clients MAY query by schema or schema extensions by using a filter Clients MAY query by schema or schema extensions by using a filter
expression including the "schemas" attribute. expression including the "schemas" attribute.
The following are examples of valid filters. Some attributes (e.g. The following are examples of valid filters. Some attributes (e.g.,
rooms and rooms.number) are hypothetical extensions and are not part rooms and rooms.number) are hypothetical extensions and are not part
of SCIM core schema: of SCIM core schema:
filter=userName eq "bjensen" filter=userName eq "bjensen"
filter=name.familyName co "O'Malley" filter=name.familyName co "O'Malley"
filter=userName sw "J" filter=userName sw "J"
filter=urn:ietf:params:scim:schemas:core:2.0:User:userName sw "J" filter=urn:ietf:params:scim:schemas:core:2.0:User:userName sw "J"
skipping to change at page 20, line 43 skipping to change at page 20, line 43
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.4.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].
The following table describes the URL pagination parameters. The following table describes the URL pagination parameters.
+------------+----------------------------+-------------------------+ +------------+----------------------------+-------------------------+
| Parameter | Description | Default | | Parameter | Description | Default |
+------------+----------------------------+-------------------------+ +------------+----------------------------+-------------------------+
skipping to change at page 25, line 46 skipping to change at page 25, line 46
... ...
] ]
} }
Figure 5: Example POST Query Response Figure 5: Example POST Query Response
3.5. 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.5.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.
skipping to change at page 26, line 38 skipping to change at page 26, line 38
attributes SHALL be removed or defaulted. Clients that would like attributes SHALL be removed or defaulted. Clients that would like
to override a server defaults, MAY specify "null" for a single- to override a server defaults, MAY specify "null" for a single-
valued attribute or an empty array "[]" for a multi-valued valued attribute or an empty array "[]" for a multi-valued
attribute to clear all values. attribute to clear all values.
immutable If value(s) are already set for the attribute, the input immutable If value(s) are already set for the attribute, the input
value(s) MUST match or HTTP status 400 SHOULD be returned with value(s) MUST match or HTTP status 400 SHOULD be returned with
error code "mutability". If the service provider has no existing error code "mutability". If the service provider has no existing
values, the new value(s) SHALL be applied. values, the new value(s) SHALL be applied.
readOnly Any values provided (e.g. meta.resourceType) SHALL be readOnly Any values provided (e.g., meta.resourceType) SHALL be
ignored. ignored.
If an attribute is "required", clients MUST specify the attribute in If an attribute is "required", clients MUST specify the attribute in
the PUT request. the PUT request.
Unless otherwise specified a successful PUT operation returns a 200 Unless otherwise specified a successful PUT operation returns a 200
OK response code and the entire resource within the response body, OK response code and the entire resource within the response body,
enabling the client to correlate the client's and the service enabling the client to correlate the client's and the service
provider's views of the updated resource. Example: provider's views of the updated resource. Example:
skipping to change at page 29, line 19 skipping to change at page 29, line 19
The body of an HTTP PATCH request MUST contain the attribute The body of an HTTP PATCH request MUST contain the attribute
"Operations", whose value is an array of one or more patch "Operations", whose value is an array of one or more patch
operations. Each patch operation object MUST have exactly one "op" operations. Each patch operation object MUST have exactly one "op"
member, whose value indicates the operation to perform and MAY be one member, whose value indicates the operation to perform and MAY be one
of "add", "remove", or "replace". The semantics of each operation of "add", "remove", or "replace". The semantics of each operation
are defined in the following sub-sections. are defined in the following sub-sections.
The following is an example representation of a PATCH request showing The following is an example representation of a PATCH request showing
the basic JSON structure (non-normative): the basic JSON structure (non-normative):
{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], { "schemas":
"Operations":[ ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
{ "Operations":[
"op":"add",
"path":"members",
"value":[
{ {
"display": "Babs Jensen", "op":"add",
"$ref": "https://example.com/v2/Users/2819c223...413861904646", "path":"members",
"value": "2819c223-7f76-453a-919d-413861904646" "value":[
} {
] "display": "Babs Jensen",
}, "$ref":
... + additional operations if needed ... "https://example.com/v2/Users/2819c223...413861904646",
] "value": "2819c223-7f76-453a-919d-413861904646"
} }
]
},
... + additional operations if needed ...
]
}
Figure 6: Example JSON body for SCIM PATCH Request Figure 6: Example JSON body for SCIM PATCH Request
A "path" attribute value is a String containing an attribute path A "path" attribute value is a String containing an attribute path
describing the target of the operation. The "path" attribute is describing the target of the operation. The "path" attribute is
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:
skipping to change at page 31, line 5 skipping to change at page 31, line 8
resource's "schemas" attribute. resource's "schemas" attribute.
Each patch operation represents a single action to be applied to the Each patch operation represents a single action to be applied to the
same SCIM resource specified by the request URI. Operations are same SCIM resource specified by the request URI. Operations are
applied sequentially in the order they appear in the array. Each applied sequentially in the order they appear in the array. Each
operation in the sequence is applied to the target resource; the operation in the sequence is applied to the target resource; the
resulting resource becomes the target of the next operation. resulting resource becomes the target of the next operation.
Evaluation continues until all operations are successfully applied or Evaluation continues until all operations are successfully applied or
until an error condition is encountered. until an error condition is encountered.
For a multi-valued attributes, a patch operation that sets a value's For multi-valued attributes, a patch operation that sets a value's
"primary" attribute to "true", SHALL cause the server to "primary" sub-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.
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.12. 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 within the response body,
query parameter - see Additional Retrieval Query Parameters subject to the "attributes" query parameter (see Additional Retrieval
(Section 3.9) ) within the response body, or a 204 No Content Query Parameters (Section 3.9)); or the server MAY return a 204 No
response code and the appropriate response headers for a successful Content response code and the appropriate response headers for a
patch request. The server MUST return a 200 OK if the "attributes" successful patch request. The server MUST return a 200 OK if the
parameter is specified on the request. "attributes" parameter is specified on the request.
3.5.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
indicated by "path" references: indicated by "path" references:
o If omitted, the target location is assumed to be the resource o If omitted, the target location is assumed to be the resource
itself. The "value" parameter contains a set of attributes to be itself. The "value" parameter contains a set of attributes to be
added to the resource. added to the resource.
skipping to change at page 32, line 22 skipping to change at page 32, line 25
o If the target location already contains the value specified, no o If the target location already contains the value specified, no
changes SHOULD be made to the resource and a success response changes SHOULD be made to the resource and a success response
SHOULD be returned. Unless other operations change the resource, SHOULD be returned. Unless other operations change the resource,
this operation SHALL NOT change the modify timestamp of the this operation SHALL NOT change the modify timestamp of the
resource. resource.
The following example shows how to add a member to a group. Some The following example shows how to add a member to a group. Some
text removed for readability ("..."): text removed for readability ("..."):
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-...-9b4da3f908ce
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
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], { "schemas":
"Operations":[ ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
{ "Operations":[
"op":"add",
"path":"members",
"value":[
{ {
"display": "Babs Jensen", "op":"add",
"$ref": "https://example.com/v2/Users/2819c223...413861904646", "path":"members",
"value": "2819c223-7f76-453a-919d-413861904646" "value":[
{
"display": "Babs Jensen",
"$ref":
"https://example.com/v2/Users/2819c223...413861904646",
"value": "2819c223-7f76-453a-919d-413861904646"
}
]
} }
] ]
} }
]
}
If the user was already a member of this group, no changes should be If the user was already a member of this group, no changes should be
made to the resource and a success response should be returned. The made to the resource and a success response should be returned. The
server responds with either the entire updated Group or no response server responds with either the entire updated Group or no response
body: body:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
ETag: W/"b431af54f0671a2" ETag: W/"b431af54f0671a2"
Location: Location:
"https://example.com/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" "https://example.com/Groups/acbf3ae7-8463-...-9b4da3f908ce"
The following example shows how to add one or more attributes to a The following example shows how to add one or more attributes to a
User resource without using a "path" attribute. User resource without using a "path" attribute.
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
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
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[{ "Operations":[{
"op":"add", "op":"add",
"value":{ "value":{
"emails":[ "emails":[
{ {
"value":"babs@jensen.org", "value":"babs@jensen.org",
"type":"home" "type":"home"
} }
], ],
"nickname":"Babs" "nickname":"Babs"
skipping to change at page 35, line 8 skipping to change at page 35, line 8
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
readability ("..."): readability ("..."):
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-...-9b4da3f908ce
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
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[{ "Operations":[{
"op":"remove", "op":"remove",
"path":"members[value eq \"2819c223-7f76-...413861904646\"]" "path":"members[value eq \"2819c223-7f76-...413861904646\"]"
}] }]
} }
Remove all members of a group: Remove all members of a group:
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-...-9b4da3f908ce
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
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], { "schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[{ "Operations":[{
"op":"remove","path":"members" "op":"remove","path":"members"
}] }]
} }
Removal of a value from a complex-multi-valued attribute (request Removal of a value from a complex-multi-valued attribute (request
headers removed for brevity): headers removed for brevity):
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{ "Operations": [{
"op":"remove", "op":"remove",
"path":"emails[type eq \"work\" and value ew \"example.com\"]" "path":"emails[type eq \"work\" and value ew \"example.com\"]"
}] }]
} }
Example request to remove and add a member. Some text removed for Example request to remove and add a member. Some text removed for
readability ("..."): readability ("..."):
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-...-9b4da3f908ce
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
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], { "schemas":
"Operations": [ ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
{ "Operations": [
"op":"remove", {
"path":"members[value eq\"2819c223...919d-413861904646\"]" "op":"remove",
}, "path":
{ "members[value eq\"2819c223...919d-413861904646\"]"
"op":"add", },
"path":"members", {
"value": [ "op":"add",
{ "path":"members",
"display": "James Smith", "value": [
"$ref":"https://example.com/v2/Users/08e1d05d...473d93df9210", {
"value": "08e1d05d...473d93df9210" "display": "James Smith",
} "$ref":
] "https://example.com/v2/Users/08e1d05d...473d93df9210",
} "value": "08e1d05d...473d93df9210"
] }
} ]
}
]
}
The following example shows how to replace all the members of a group The following example shows how to replace all the members of a group
with a different members list. Some text removed for readabilty with a different members list. Some text removed for readabilty
("..."): ("..."):
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
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
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "schemas":
"Operations": [ ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
{ "Operations": [
"op":"remove","path":"members"
},
{
"op":"add",
"path":"members",
"value":[
{ {
"display": "Babs Jensen", "op":"remove","path":"members"
"$ref": "https://example.com/v2/Users/2819c223...413861904646",
"value": "2819c223-7f76-453a-919d-413861904646"
}, },
{ {
"display": "James Smith", "op":"add",
"$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", "path":"members",
"value": "08e1d05d-121c-4561-8b96-473d93df9210" "value":[
}] {
} "display": "Babs Jensen",
] "$ref":
} "https://example.com/v2/Users/2819c223...413861904646",
"value": "2819c223-7f76-453a-919d-413861904646"
},
{
"display": "James Smith",
"$ref":
"https://example.com/v2/Users/08e1d05d...473d93df9210",
"value": "08e1d05d-121c-4561-8b96-473d93df9210"
}]
}
]
}
3.5.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.
skipping to change at page 38, line 18 skipping to change at page 38, line 21
o If the target location path specifies an attribute that does not o If the target location path specifies an attribute that does not
exist, the service provider SHALL treat the operation as an "add". exist, the service provider SHALL treat the operation as an "add".
o If the target location specifies a complex attribute, a set of o If the target location specifies a complex attribute, a set of
sub-attributes SHALL be specified in the "value" parameter which sub-attributes SHALL be specified in the "value" parameter which
replaces any existing values or adds where an attribute did not replaces any existing values or adds where an attribute did not
previously exist. Sub-attributes that are not specified in the previously exist. Sub-attributes that are not specified in the
"value" parameter are left unchanged. "value" parameter are left unchanged.
o If the target location is a multi-valued attribute and a value o If the target location is a multi-valued attribute and a value
selction ("valuePath") filter is specified that matches one or selection ("valuePath") filter is specified that matches one or
more values of the mulit-valued attribute, then all matching more values of the mulit-valued attribute, then all matching
record values SHALL be replaced. record values SHALL be replaced.
o If the target location is a complex-multi-valued attribute with a o If the target location is a complex-multi-valued attribute with a
value selection filter ("valuePath") and a specific sub-attribute value selection filter ("valuePath") and a specific sub-attribute
(e.g. "addresses[type eq "work"].streetAddress" ), the matching (e.g., "addresses[type eq "work"].streetAddress" ), the matching
sub-attribute of all matching records is replaced. sub-attribute of all matching records is replaced.
o If the target location is a mulit-valued attribute for which a o If the target location is a mulit-valued attribute for which a
value selection filter ("valuePath") has been supplied and no value selection filter ("valuePath") has been supplied and no
record match was made, the service provider SHALL fail by record match was made, the service provider SHALL fail by
returning HTTP status "400", and a "scimType" of "noTarget". returning HTTP status "400", and a "scimType" of "noTarget".
The following example shows how to replace all the members of a group The following example shows how to replace all the members of a group
with a different members list in a single replace operation. Some with a different members list in a single replace operation. Some
text removed for readability ("..."): text removed for readability ("..."):
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
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
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "schemas":
"Operations": [{ ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"op":"replace", "Operations": [{
"path":"members", "op":"replace",
"value":[ "path":"members",
{ "value":[
"display": "Babs Jensen", {
"$ref": "https://example.com/v2/Users/2819c223...413861904646", "display": "Babs Jensen",
"value": "2819c223...413861904646" "$ref":
}, "https://example.com/v2/Users/2819c223...413861904646",
{ "value": "2819c223...413861904646"
"display": "James Smith", },
"$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", {
"value": "08e1d05d...473d93df9210" "display": "James Smith",
} "$ref":
] "https://example.com/v2/Users/08e1d05d...473d93df9210",
}] "value": "08e1d05d...473d93df9210"
} }
]
}]
}
The following example shows how to change a User's entire "work" The following example shows how to change a User's entire "work"
address using a "valuePath" filter. Note that by setting "primary" address using a "valuePath" filter. Note that by setting "primary"
to "true", the service provider will reset primary to "false" for any to "true", the service provider will reset primary to "false" for any
other existing values of "addresses". other existing values of "addresses".
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
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
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "schemas":
"Operations": [{ ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"op":"replace", "Operations": [{
"path":"addresses[type eq \"work\"]", "op":"replace",
"value": "path":"addresses[type eq \"work\"]",
{ "value":
"type": "work", {
"streetAddress": "911 Universal City Plaza", "type": "work",
"locality": "Hollywood", "streetAddress": "911 Universal City Plaza",
"region": "CA", "locality": "Hollywood",
"postalCode": "91608", "region": "CA",
"country": "US", "postalCode": "91608",
"formatted": "911 Universal City Plaza\nHollywood, CA 91608 US", "country": "US",
"primary": true "formatted":
} "911 Universal City Plaza\nHollywood, CA 91608 US",
}] "primary": true
} }
}]
}
The following example shows how to change a specific sub-attribute The following example shows how to change a specific sub-attribute
"streetAddress" of complex attribute "emails" selected by "valuePath" "streetAddress" of complex attribute "emails" selected by "valuePath"
filter: filter:
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
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
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{ "Operations": [{
"op":"replace", "op":"replace",
"path":"addresses[type eq \"work\"].streetAddress", "path":"addresses[type eq \"work\"].streetAddress",
"value":"1010 Broadway Ave" "value":"1010 Broadway Ave"
}] }]
} }
The following example shows how to replace all values of one or more The following example shows how to replace all values of one or more
specific attributes of a User resource. Note that other attributes specific attributes of a User resource. Note that other attributes
are unaffected. are unaffected.
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
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
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{ "Operations": [{
"op":"replace", "op":"replace",
"value":"{ "value":"{
"emails":[ "emails":[
{ {
"value":"bjensen@example.com", "value":"bjensen@example.com",
"type":"work", "type":"work",
"primary":true "primary":true
}, },
{ {
skipping to change at page 42, line 44 skipping to change at page 42, line 45
3.6. 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.
DELETE /Users/2819c223-7f76-453a-919d-413861904646 DELETE /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"c310cd84f0281b7" If-Match: W/"c310cd84f0281b7"
In response to a successful delete, the server SHALL respond with In response to a successful delete, the server SHALL respond with
successful HTTP status 204 (No Content). A non-normative example successful HTTP status 204 (No Content). A non-normative example
response: response:
skipping to change at page 45, line 29 skipping to change at page 45, line 29
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.7.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.7.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
skipping to change at page 53, line 14 skipping to change at page 53, line 14
attribute status MUST include the code attribute that holds the HTTP attribute status MUST include the code attribute that holds the HTTP
response code that would have been returned if a single HTTP request response code that would have been returned if a single HTTP request
would have been used. If an error occurred the status MUST also would have been used. If an error occurred the status MUST also
include the description attribute containing a human readable include the description attribute containing a human readable
explanation of the error. explanation of the error.
"status": "201" "status": "201"
The following is an example of a status in a failed operation. The following is an example of a status in a failed operation.
"status": "400", "status": "400",
"response":{ "response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax" "scimType":"invalidSyntax"
"detail": "detail":
"Request is unparseable, syntactically incorrect, or violates schema.", "Request is unparsable, syntactically incorrect, or violates schema.",
"status":"400" "status":"400"
} }
The following example shows how to add, update, and remove a user. The following example shows how to add, update, and remove a user.
The "failOnErrors" attribute is set to '1' indicating the service The "failOnErrors" attribute is set to '1' indicating the service
provider should return on the first error. The POST operation's provider should return on the first error. The POST operation's
bulkId value is set to 'qwerty' enabling the client to match the new bulkId value is set to 'qwerty' enabling the client to match the new
User with the returned resource id '92b725cd-9465-4e7d- User with the returned resource id '92b725cd-9465-4e7d-
8c16-01f8e146b87a'. 8c16-01f8e146b87a'.
POST /v2/Bulk POST /v2/Bulk
Host: example.com Host: example.com
skipping to change at page 56, line 5 skipping to change at page 56, line 5
} }
] ]
} }
The following response is returned if an error occurred when The following response is returned if an error occurred when
attempting to create the User 'Alice'. The service provider stops attempting to create the User 'Alice'. The service provider stops
processing the bulk operation and immediately returns a response to processing the bulk operation and immediately returns a response to
the client. The response contains the error and any successful the client. The response contains the error and any successful
results prior to the error. results prior to the error.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"bulkId": "qwerty", "bulkId": "qwerty",
"status": "400", "status": "400",
"response":{ "response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax" "scimType":"invalidSyntax"
"detail": "detail":
"Request is unparseable, syntactically incorrect, or violates schema.", "Request is unparsable, syntactically incorrect, or violates schema.",
"status":"400" "status":"400"
} }
} }
] ]
} }
If the "failOnErrors" attribute is not specified or the service If the "failOnErrors" attribute is not specified or the service
provider has not reached the error limit defined by the client the provider has not reached the error limit defined by the client the
service provider will continue to process all operations. The service provider will continue to process all operations. The
following is an example in which all operations failed. following is an example in which all operations failed.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"bulkId": "qwerty", "bulkId": "qwerty",
"status": "400", "status": "400",
"response":{ "response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax" "scimType":"invalidSyntax"
"detail": "detail":
"Request is unparseable, syntactically incorrect, or violates schema.", "Request is unparsable, syntactically incorrect, or violates schema.",
"status":"400" "status":"400"
} }
}, },
{ {
"location": "location":
"https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT", "method": "PUT",
"status": "412", "status": "412",
"response":{ "response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
skipping to change at page 60, line 8 skipping to change at page 60, line 8
"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.9. 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.10) 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.10) 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 61, line 35 skipping to change at page 61, line 35
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". 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.11. "/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
skipping to change at page 62, line 22 skipping to change at page 62, line 22
o A service provider MAY process the SCIM request directly. In any o A service provider MAY process the SCIM request directly. In any
response, the HTTP "Location" header MUST be the permanent response, the HTTP "Location" header MUST be the permanent
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.12. 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
skipping to change at page 63, line 18 skipping to change at page 63, line 18
| | | permanent reference to the | | | | permanent reference to the |
| | | resource and SHOULD continue to | | | | resource and SHOULD continue to |
| | | use the original request URI | | | | use the original request URI |
| | | [RFC7231]. | | | | [RFC7231]. |
| 308 | GET, POST, | The client is directed to repeat | | 308 | GET, POST, | The client is directed to repeat |
| PERMANENT | PUT, PATCH, | the same HTTP request at the | | PERMANENT | PUT, PATCH, | the same HTTP request at the |
| REDIRECT | DELETE | location identified. The client | | REDIRECT | DELETE | location identified. The client |
| | | SHOULD use the location provided | | | | SHOULD use the location provided |
| | | in the response as the permanent | | | | in the response as the permanent |
| | | reference to the resource | | | | reference to the resource |
| | | [RFC7238]. | | | | [RFC7538]. |
| 400 BAD | GET, POST, | Request is unparseable, | | 400 BAD | GET, POST, | Request is unparsable, |
| REQUEST | PUT, PATCH, | syntactically incorrect, or | | REQUEST | PUT, PATCH, | syntactically incorrect, or |
| | DELETE | violates schema | | | DELETE | violates schema |
| 401 | GET, POST, | Authorization failure | | 401 | GET, POST, | Authorization failure |
| UNAUTHORIZED | PUT, PATCH, | | | UNAUTHORIZED | PUT, PATCH, | |
| | DELETE | | | | DELETE | |
| 403 | GET, POST, | Server does not support requested | | 403 | GET, POST, | Server does not support requested |
| FORBIDDEN | PUT, PATCH, | operation | | FORBIDDEN | PUT, PATCH, | operation |
| | DELETE | | | | DELETE | |
| 404 NOT | GET, POST, | Specified resource (e.g., User) or | | 404 NOT | GET, POST, | Specified resource (e.g., User) or |
| FOUND | PUT, PATCH, | end-point, does not exist | | FOUND | PUT, PATCH, | end-point, does not exist |
skipping to change at page 64, line 36 skipping to change at page 64, line 36
| | 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.3), PUT | | | values is already in use or | Section 3.3), PUT |
| | is reserved. | (Section 3.5.1), | | | is reserved. | (Section 3.5.1), |
| | | PATCH (Section | | | | PATCH (Section |
| | | 3.5.2) | | | | 3.5.2) |
| mutability | The attempted modification | PUT (Section | | mutability | The attempted modification | PUT (Section |
| | is not compatible with the | 3.5.1), PATCH | | | is not compatible with the | 3.5.1), PATCH |
| | target attributes mutability | (Section 3.5.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.4.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.3, Bulk - Section | | | schema. | 3.3, Bulk - Section |
| | | 3.7), PUT (Section | | | | 3.7), PUT (Section |
| | | 3.5.1) | | | | 3.5.1) |
| invalidPath | The path attribute was | PATCH (Section | | invalidPath | The path attribute was | PATCH (Section |
skipping to change at page 69, line 7 skipping to change at page 69, line 7
schemas endpoint. For example: schemas endpoint. For example:
/Schemas/urn:ietf:params:scim:schemas:core:2.0:User /Schemas/urn:ietf:params:scim:schemas:core:2.0:User
The contents of each schema returned is described in Section 7 The contents of each schema returned is described in Section 7
[I-D.ietf-scim-core-schema]. An example representation of SCIM [I-D.ietf-scim-core-schema]. An example representation of SCIM
schemas may be found in Section 8.7 [I-D.ietf-scim-core-schema]. schemas may be found in Section 8.7 [I-D.ietf-scim-core-schema].
/ResourceTypes /ResourceTypes
An HTTP GET to this endpoint is used to discover the types of An HTTP GET to this endpoint is used to discover the types of
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.4.1. When returning User or Group is retrieved as per Section 3.4.1. When returning
skipping to change at page 70, line 48 skipping to change at page 70, line 48
"location":"https://example.com/v2/ResourceTypes/Group", "location":"https://example.com/v2/ResourceTypes/Group",
"resourceType": "ResourceType" "resourceType": "ResourceType"
} }
}] }]
} }
Figure 9: Example Resource Type JSON Representation Figure 9: Example Resource Type JSON Representation
5. Preparation and Comparison of Internationalized Strings 5. Preparation and Comparison of Internationalized Strings
To increase the likelihood that the input and comparison of unicode To increase the likelihood that the input and comparison of usernames
usernames and passwords will work in ways that make sense for typical and passwords will work in ways that make sense for typical users
users throughout the world there are special string preparation and throughout the world, there are rules for preparing, enforcing, and
comparison methods (PRECIS) that MUST be followed for usernames and comparing internationalized strings that represent usernames and
passwords. Before comparing or evaluating uniqueness of a "userName" passwords. Before comparing or evaluating uniqueness of a "userName"
or "password" attribute, service providers MUST use the "PRECIS" or "password" attribute, service providers MUST use the "PRECIS"
profile described in Sections 4 and 5 respectively of profile described in Sections 4 and 5 respectively of
[I-D.ietf-precis-saslprepbis] and is based on the "PRECIS" framework [I-D.ietf-precis-saslprepbis] which is based on the "PRECIS"
specification [I-D.ietf-precis-framework]. framework specification [I-D.ietf-precis-framework].
6. Multi-Tenancy 6. Multi-Tenancy
A single service provider may expose the SCIM protocol to multiple A single service provider may expose the SCIM protocol to multiple
clients. Depending on the nature of the service, the clients may clients. Depending on the nature of the service, the clients may
have authority to access and alter resources initially created by have authority to access and alter resources initially created by
other clients. Alternatively, clients may expect to access disjoint other clients. Alternatively, clients may expect to access disjoint
sets of resources, and may expect that their resources are sets of resources, and may expect that their resources are
inaccessible by other clients. These scenarios are called "multi- inaccessible by other clients. These scenarios are called "multi-
tenancy", where each client is understood to be or represent a tenancy", where each client is understood to be or represent a
skipping to change at page 73, line 13 skipping to change at page 73, line 13
over time, and depend on the widespread deployment and known security over time, and depend on the widespread deployment and known security
vulnerabilities at the time of implementation. At the time of this vulnerabilities at the time of implementation. At the time of this
writing, TLS version 1.2 [RFC5246] is the most recent version, but writing, TLS version 1.2 [RFC5246] is the most recent version, but
has very limited actual deployment, and might not be readily has very limited actual deployment, and might not be readily
available in implementation toolkits. TLS version 1.0 [RFC5246] is available in implementation toolkits. TLS version 1.0 [RFC5246] is
the most widely deployed version, and will give the broadest the most widely deployed version, and will give the broadest
interoperability. interoperability.
7.2. Disclosure of Sensitive Information in URIs 7.2. Disclosure of Sensitive Information in URIs
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.4.3 ). Section 3.4.3 ).
skipping to change at page 74, line 8 skipping to change at page 74, line 8
7.3. Anonymous Requests 7.3. Anonymous Requests
If a SCIM service provider accepts anonymous requests such as SCIM If a SCIM service provider accepts anonymous requests such as SCIM
resource creation requests (via HTTP POST), appropriate security resource creation requests (via HTTP POST), appropriate security
measures should be put in place to prevent or limit exposure to measures should be put in place to prevent or limit exposure to
attacks. The following counter-measures MAY be used: attacks. The following counter-measures MAY be used:
o Try to authenticate web UI components that forumulate the SCIM o Try to authenticate web UI components that forumulate the SCIM
creation request. While the end-user MAY be anonymous, the web creation request. While the end-user MAY be anonymous, the web
user interface component often has its own way to authenticate to user interface component often has its own way to authenticate to
the SCIM service provider (e.g. has an OAuth Client Credential the SCIM service provider (e.g., has an OAuth Client Credential
[RFC6749]) and the web user interface component may implement its [RFC6749]) and the web user interface component may implement its
own measures (e.g. such as CAPTCHA) to ensure a ligitimate request own measures (e.g., such as CAPTCHA) to ensure a ligitimate
is being made. request is being made.
o Limit the number of requests any particular client MAY make in a o Limit the number of requests any particular client MAY make in a
period of time. period of time.
o For User resources, default newly created resource with an o For User resources, default newly created resource with an
"active" setting of "false" and use a secondary confirmation "active" setting of "false" and use a secondary confirmation
process (e.g. email confirmation) to ensure the resource created process (e.g., email confirmation) to ensure the resource created
is real. is real.
7.4. HTTP Considerations 7.4. HTTP Considerations
As an HTTP based protocol, implementers of SCIM SHOULD consider all As an HTTP based protocol, implementers of SCIM SHOULD consider all
security considerations of the HTTP/1.1 as enumerated in Section 1 security considerations of the HTTP/1.1 as enumerated in Section 1
[RFC7230] [RFC7230]
As stated in Section 2.7.1 [RFC7230], a SCIM client MUST NOT generate As stated in Section 2.7.1 [RFC7230], a SCIM client MUST NOT generate
the userinfo (i.e. username and password) component (and its "@" the userinfo (i.e., username and password) component (and its "@"
delimiter) when an "http" URI reference is generated with a message delimiter) when an "http" URI reference is generated with a message
as they are now disallowed in HTTP. as they are now disallowed in HTTP.
7.5. Secure Storage and Handling of Sensitive Data 7.5. Secure Storage and Handling of Sensitive Data
An attacker may obtain valid username/password combinations from the An attacker may obtain valid username/password combinations from the
SCIM service provider's underlying database by gaining access to the SCIM service provider's underlying database by gaining access to the
database and/or launching injection attacks. This could lead to database and/or launching injection attacks. This could lead to
unintended disclosure of username/password combinations. The impact unintended disclosure of username/password combinations. The impact
may extend beyond the domain of the SCIM service provider if the data may extend beyond the domain of the SCIM service provider if the data
was provisioned from other domains. was provisioned from other domains.
Administrators should undertake industry best practices to protect Administrators should undertake industry best practices to protect
the storage of credentials and in particular SHOULD follow the storage of credentials and in particular SHOULD follow
recommendations outlines in Section 5.1.4.1 [RFC6819]. These recommendations outlines in Section 5.1.4.1 [RFC6819]. These
recommendations include but are not limited to: recommendations include but are not limited to:
o Provide injection attack counter measures (e.g. by validating all o Provide injection attack counter measures (e.g., by validating all
inputs and parameters), inputs and parameters),
o No cleartext storage of credentials, o No cleartext storage of credentials,
o Store credentials using an encrypted protection mechanism, and o Store credentials using an encrypted protection mechanism, and
o Avoid passwords and consider use of asymmetric cryptography based o Avoid passwords and consider use of asymmetric cryptography based
credentials. credentials.
As outlined in Section 5.1.4.2 [RFC6819], adminitrators SHOULD take As outlined in Section 5.1.4.2 [RFC6819], adminitrators SHOULD take
counter measures to prevent online attacks on secrets such as: counter measures to prevent online attacks on secrets such as:
skipping to change at page 75, line 24 skipping to change at page 75, line 24
a number of failed attempts, a number of failed attempts,
o Use "tar pit" techniques by temporarily locking a respective o Use "tar pit" techniques by temporarily locking a respective
account and delaying responses for a certain duration. The account and delaying responses for a certain duration. The
duration may increase with the number of failed attempts, and duration may increase with the number of failed attempts, and
o Use authentication system that use CAPTCHA's and other factors for o Use authentication system that use CAPTCHA's and other factors for
authenticating users further reducing the possibility of automated authenticating users further reducing the possibility of automated
attacks. attacks.
7.6. Case Insensitive Comparision & International Languages 7.6. Case Insensitive Comparison & International Languages
When comparing unicode strings such as in query filters or testing When comparing unicode strings such as in query filters or testing
for uniqueness of usernames and passwords, strings MUST be for uniqueness of usernames and passwords, strings MUST be
appopriately prepared before comparison. See Section 5. appropriately prepared before comparison. See Section 5.
8. IANA Considerations 8. IANA Considerations
8.1. Media Type Registration 8.1. Media Type Registration
To: ietf-types@iana.org To: ietf-types@iana.org
Subject: Registration of media type application/scim+json Subject: Registration of media type application/scim+json
Type name: application Type name: application
skipping to change at page 76, line 12 skipping to change at page 76, line 12
Interoperability considerations: The "application/scim+json" media Interoperability considerations: The "application/scim+json" media
type is intended to identify JSON structure data that conforms to type is intended to identify JSON structure data that conforms to
the SCIM protocol and schema specifications. Older versions of the SCIM protocol and schema specifications. Older versions of
SCIM are known to informally use "application/json". SCIM are known to informally use "application/json".
Published specification: [[this document]] Published specification: [[this document]]
Applications that use this media type: It is expected that Applications that use this media type: It is expected that
applications that use this type may be special purpose applications that use this type may be special purpose
applications intended for inter-domain provisioning. Clients may applications intended for inter-domain provisioning. Clients may
also be applications (e.g. mobile applications) that need to use also be applications (e.g., mobile applications) that need to use
SCIM for self-registration of user accounts. SCIM services may be SCIM for self-registration of user accounts. SCIM services may be
offered by web applications that offer support for standards based offered by web applications that offer support for standards based
provisioning or may be a dedicated SCIM service provider such as a provisioning or may be a dedicated SCIM service provider such as a
"cloud directory". Content may be treated as equivalent to "cloud directory". Content may be treated as equivalent to
"application/json" type for the purpose of displaying in web "application/json" type for the purpose of displaying in web
browsers. browsers.
Additional information: Additional information:
Magic number(s): Magic number(s):
skipping to change at page 77, line 32 skipping to change at page 77, line 32
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-14 (work in progress), March 2015. saslprepbis-15 (work in progress), April 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-17 (work in Schema", draft-ietf-scim-core-schema-17 (work in
progress), March 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.
skipping to change at page 78, line 28 skipping to change at page 78, line 28
[RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Semantics and Content", RFC 7231, June 2014. (HTTP/1.1): Semantics and Content", RFC 7231, June 2014.
[RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext [RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext
Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233,
June 2014. June 2014.
[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.
[RFC7538] Reschke, J., "The Hypertext Transfer Protocol Status Code
308 (Permanent Redirect)", RFC 7538, April 2015.
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-23 (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", Dec 2005.
[Order-Operations] [Order-Operations]
Wikipedia, "Order of Operations: Programming Languages", . Wikipedia, "Order of Operations: Programming Languages",
Apr 2015.
[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.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, October 2012. Framework: Bearer Token Usage", RFC 6750, October 2012.
[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
308 (Permanent Redirect)", RFC 7238, June 2014.
[XML-Schema] [XML-Schema]
Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes
Second Edition", October 2004. 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)
 End of changes. 92 change blocks. 
252 lines changed or deleted 285 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/