One document matched: draft-ietf-scim-api-19.xml
<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type='text/xsl' href='http://xml.resource.org/authoring/rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-ietf-scim-api-19" ipr="trust200902">
<front>
<title abbrev="draft-ietf-scim-api">System for Cross-Domain Identity
Management: Protocol</title>
<author fullname="Phil Hunt" initials="P." role="editor" surname="Hunt">
<organization abbrev="Oracle">Oracle Corporation</organization>
<address>
<email>phil.hunt@yahoo.com</email>
</address>
</author>
<author fullname="Kelly Grizzle" initials="K.G." surname="Grizzle">
<organization abbrev="SailPoint">SailPoint</organization>
<address>
<email>kelly.grizzle@sailpoint.com</email>
</address>
</author>
<author fullname="Morteza Ansari" initials="M.A." surname="Ansari">
<organization abbrev="Cisco">Cisco</organization>
<address>
<email>morteza.ansari@cisco.com</email>
</address>
</author>
<author fullname="Erik Wahlström" initials="E.W." surname="Wahlström">
<organization abbrev="Nexus Technology"/>
<address>
<email>erik.wahlstrom@nexusgroup.com</email>
</address>
</author>
<author fullname="Chuck Mortimore" initials="C." surname="Mortimore">
<organization abbrev="Salesforce">Salesforce.com</organization>
<address>
<email>cmortimore@salesforce.com</email>
</address>
</author>
<date month="May" year="2015"/>
<keyword>SCIM</keyword>
<abstract>
<t>The System for Cross-Domain Identity Management (SCIM) specification
is an HTTP based protocol that makes managing identities in multi-domain
scenarios easier to support through a standardized service. Examples
include but are not limited to enterprise to cloud service providers,
and inter-cloud based scenarios. The specification suite seeks to build
upon experience with existing schemas and deployments, placing specific
emphasis on simplicity of development and integration, while applying
existing authentication, authorization, and privacy models. SCIM's
intent is to reduce the cost and complexity of user management
operations by providing a common user schema, an extension model, and a
service protocol defined by this document.</t>
</abstract>
</front>
<middle>
<section anchor="intro" title="Introduction and Overview" toc="default">
<t>The SCIM Protocol is an application-level, HTTP protocol for
provisioning and managing identity data on the web and in cross-domain
environments such as enterprise to cloud, or inter-cloud scenarios. The
protocol supports creation, modification, retrieval, and discovery of
core identity resources such as Users and Groups, as well as custom
resources and resource extensions.</t>
<t>The definition of resources, attributes, and overall schema are
defined in the SCIM Core Schema document (see <xref
target="I-D.ietf-scim-core-schema"/>). [[RFC Editor: These
specifications should be published together]]</t>
<section title="Intended Audience" toc="default">
<t>This document is intended as a guide to SCIM protocol usage for
both SCIM HTTP service providers and HTTP clients who may provision
information to service providers or retrieve information from
them.</t>
</section>
<section anchor="notat" title="Notational Conventions" toc="default">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in <xref
target="RFC2119"/>. These keywords are capitalized when used to
unambiguously specify requirements of the protocol or application
features and behavior that affect the interoperability and security of
implementations. When these words are not capitalized, they are meant
in their natural-language sense.</t>
<t>For purposes of readability examples are not URL encoded.
Implementers MUST percent encode URLs as described in <xref
target="RFC3986">Section 2.1 of</xref>.</t>
<t>Throughout this documents all figures may contain spaces and extra
line-wrapping for readability and space limitations. Similarly, some
URI's contained within examples, have been shortened for space and
readability reasons.</t>
</section>
<section anchor="defs" title="Definitions" toc="default">
<t>This specification uses the definitions from <xref
target="I-D.ietf-scim-core-schema"/>, and defines the following
additional terms:<list style="hanging">
<t hangText="Base URI"><vspace/>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 clients MAY append additional
path information and query parameters as part of forming the
request. The base URI most often is a URL which most often
consists of the <spanx style="verb">https</spanx> protocol scheme,
a domain name and some initial path <xref target="RFC3986"/>.
Example: <spanx style="verb">https://example.com/scim/</spanx></t>
<t>For readability, all examples in this document are expressed
assuming the SCIM service root and the server root are the same
(no path pre-fix). It is expected that SCIM servers may be
deployed using any URI path prefix. For example, a SCIM server
might be have a prefix of <spanx style="verb">https://example.com/</spanx>,
or <spanx style="verb">https://example.com/scim/tenancypath/</spanx>.
Additionally a client MAY also apply a version number to the
server root prefix (see <xref target="api-versioning"/> ).</t>
</list></t>
</section>
</section>
<section anchor="aa" title="Authentication and Authorization"
toc="default">
<t>SCIM Protocol is based upon HTTP and does not itself define a SCIM
specific scheme for authentication and authorization. SCIM depends on
the use of TLS and/or standard HTTP authentication and authorization
schemes as per <xref target="RFC7235"/>. For example, the following
methodologies could be used among others: <list style="hanging">
<t hangText="TLS Client Authentication"><vspace/>The SCIM service
provider MAY request TLS client authentication (also known as mutual
authentication). See <xref target="RFC5246">Section 7.3</xref>. </t>
<t hangText="HOBA Authentication"><vspace/>HTTP Origin-Bound
Authentication (HOBA) is a variation on TLS client authentication
and uses a digital-signature-based design for an HTTP authentication
method (see <xref target="RFC7486"/>). The design can also be used
in JavaScript-based authentication embedded in HTML. HOBA is an
alternative to HTTP authentication schemes that require passwords
and therefore avoids all problems related to passwords, such as
leakage of server-side password databases.</t>
<t hangText="Bearer Tokens"><vspace/>Bearer tokens <xref
target="RFC6750"/> MAY be used when combined with TLS and a token
framework such as OAuth 2.0 <xref target="RFC6749"/>. Tokens that
are issued based on weak or no authentication of authorizing users
and/or OAuth clients SHOULD NOT be used, unless for example, they
are being used as single-use tokens to permit one-time requests such
as anonymous registration (see <xref target="create-resource"/>).
For security considerations regarding the use of bearer tokens in
SCIM see <xref target="bearerConsiderations"/>. While bearer tokens
most often represent an authorization, it is assumed that the
authorization was based upon a successful authentication of the SCIM
client. Accordingly the SCIM service provider must have a method for
validating, parsing, and or introspecting the bearer token for the
relevant authentication and authorization information. The method
for this is assumed to be defined by the token issuing system and is
beyond the scope of this specification.</t>
<t hangText="POP Tokens"><vspace/>A proof-of-possession token
demonstrates the presenter of the token possesses a particular key
and that the recipient can cryptographically confirm
proof-of-possession of the key by the presenter. This property is
sometimes also described as the presenter being a holder-of-key. See
OAuth 2.0 Proof-of-Possession Security Architecture <xref
target="I-D.ietf-oauth-pop-architecture"/> for an example of such a
token and its use.</t>
<t hangText="Cookies"><vspace/>Javascript clients MAY assert HTTP
cookies over TLS that contain an authentication state that is
understood by the SCIM service provider (see <xref
target="RFC6265"/>). An example of this is scenarios where web-form
authentication has taken place with the user and HTTP cookies were
set representing the authentication state. For the purposes of SCIM,
the security considerations in <xref target="bearerConsiderations"/>
apply.</t>
<t hangText="Basic Authentication"><vspace/>Usage of basic
authentication should be avoided due to its use of a single factor
that is based upon a relatively static, symmetric secret.
Implementers SHOULD combine the use of basic authentication with
other factors. The security considerations of HTTP BASIC, are well
documented in <xref target="I-D.ietf-httpauth-basicauth-update"/>,
and therefore implementers are encouraged to prefer stronger
authentication methods. Designating the specific methods of
authentication and authorization are out-of-scope for SCIM, however
this information is provided as a resource to implementers.</t>
</list></t>
<t>As per <xref target="RFC7235">Section 4.1 of</xref>, a SCIM service
provider SHALL indicate supported HTTP authentication schemes via the
<spanx style="verb">WWW-Authenticate</spanx> header.</t>
<t>Regardless of methodology, the SCIM service provider MUST be able to
map the authenticated client to an access control policy in order to
determine the client's authorization to retrieve and update SCIM
resources. For example, while a browser session may have been
established via HTTP cookie or TLS client authentication, the unique
client MUST be mapped to a security subject (e.g., User). The
authorization model and the process by which this is done is beyond the
scope of this specification.</t>
<t>When processing requests, the service provider SHOULD consider the
subject performing the request and whether the action is appropriate
given the subject and the resource affected by the request. The subject
performing the request is usually determined directly or indirectly from
the <spanx style="verb">Authorization</spanx> header present in the
request. For example, a subject MAY be permitted to retrieve and update
their own <spanx style="verb">User</spanx> resource, but will normally
have restricted ability to access resources associated with other Users.
In other cases, the SCIM service provider might only grant access to a
subject's own associated <spanx style="verb">User</spanx> resource
(e.g., for the purpose of updating personal contact attributes).</t>
<t>For illustrative purposes only, SCIM protocol examples show an OAuth2
bearer token value <xref target="RFC6750"/> in the authorization header;
e.g.,<figure align="center" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1
Host: example.com
Authorization: Bearer h480djs93hd8
</artwork>
</figure>This is not intended to imply that bearer tokens are
preferred. However, the use of bearer tokens in the specification does
reflect common implementation practice. </t>
<section anchor="authzTokens" title="Use of Tokens as Authorizations">
<t>When using bearer tokens or proof-of-possession tokens that
represent an authorization grant such as issued by OAuth (see <xref
target="RFC6749"/>), implementers SHOULD consider the type of
authorization granted, any authorized scopes (see Section 3.3 of <xref
target="RFC6749"/>), and the security subject(s) that SHOULD be mapped
from the authorization when considering local access control rules.
Section 6 of the OAuth Assertions draft <xref
target="I-D.ietf-oauth-assertions"/>, documents common scenarios for
authorization including:<list style="symbols">
<t>Clients using an assertion to authenticate and/or act on behalf
of itself;</t>
<t>Clients acting on behalf of a user; and,</t>
<t>A Client acting on behalf of an anonymous user (e.g., see next
section).</t>
</list>When using OAuth authorization tokens, implementers MUST take
into account the threats and countermeasures documented in the
security considerations for the use of client authorizations (see
Section 8 of <xref target="I-D.ietf-oauth-assertions"/>). When using
other token formats or frameworks, implementers MUST take into account
similar threats and countermeasures, especially those documented by
the relevant specifications.</t>
</section>
<section title="Anonymous Requests">
<t>In some SCIM deployments it MAY be acceptable to permit
unauthenticated (anonymous) requests. For example, a user
self-registration request where the service provider chooses to accept
a SCIM Create request (see <xref target="create-resource"/>) from an
anonymous client. See <xref target="anonymous-considerations"/>, for
security considerations regarding anonymous requests.</t>
</section>
</section>
<section anchor="api" title="SCIM Protocol">
<section title="Introduction">
<t>SCIM is a protocol that is based on HTTP protocol <xref
target="RFC7230"/>. Along with HTTP headers and URIs, SCIM uses JSON
<xref target="RFC7159"/> payloads to convey both SCIM resources, as
well as protocol specific payload messages that convey request
parameters and response information such as errors. Both resources and
messages are passed in the form of JSON based structures in the
message body of an HTTP request or response. To identify this content,
SCIM uses a media type of <spanx style="verb">application/scim+json</spanx>
(see <xref target="mediaType"/>).</t>
<t>A SCIM "resource" is a JSON object <xref target="RFC7159"/> that
may be created, maintained, and retrieved through HTTP request methods
as described in this document. Each JSON resource representation
contains a <spanx style="verb">schemas</spanx> attribute that contains
a list of one or more URIs that indicate included SCIM schemas that
are used to indicate the attributes contained within a resource.
Specific information about what attributes are defined within a schema
MAY be obtained by querying a SCIM service provider's <spanx
style="verb">/Schemas</spanx> endpoint for a schema definition (see
<xref target="I-D.ietf-scim-core-schema">Section 8.7</xref>).
Responses from this endpoint describe how a service provider supports
a schema and in particular how attribute qualities such as
cardinality, case-exactness, mutability, uniqueness, returnability,
and whether an attribute is required. While SCIM schemas and
associated extension model are defined in <xref
target="I-D.ietf-scim-core-schema"/>, SCIM clients should expect that
some attribute schema may change from service provider to service
provider, particularly across administrative domains. In cases where
SCIM may be used as an open protocol in front of an application
service, it is quite reasonable to expect that some service providers
may only support a sub-set of the schema defined in <xref
target="I-D.ietf-scim-core-schema"/>.</t>
<t>A SCIM message conveys protocol parameters about a SCIM request or
response that are defined by this specification. As with a SCIM
resource, a SCIM message is a JSON object <xref target="RFC7159"/>
that contains a <spanx style="verb">schemas</spanx> attribute with a
URI whose namespace prefix that MUST begin with <spanx style="verb">urn:ietf:params:scim:api:</spanx>.
As SCIM protocol messages are fixed and defined by SCIM specifications
and registered extensions, SCIM message schemas using the above prefix
URN SHALL NOT be discoverable using the <spanx style="verb">/Schemas</spanx>
endpoint.</t>
<t>As SCIM is intended for use in cross-domain scenarios where schema
and implementations may vary, techniques such as document validation,
such as in <xref target="XML-Schema"/>, are not recommended. A SCIM
service provider interprets a request in the context of its own schema
(which may be different from the client's schema) and following the
defined processing rules for each request. The following sections in
this document define the processing rules for SCIM and provide
allowances for schema differences where appropriate. For example, in a
SCIM PUT request, <spanx style="verb">readOnly</spanx> attributes are
ignored, while <spanx style="verb">readWrite</spanx> attributes are
updated. There is no need for a SCIM client to discover which
attributes are <spanx style="verb">readOnly</spanx> and the client
does not need to remove them from a PUT request in order to be
accepted. Similarly a SCIM client SHOULD NOT expect a service provider
to return SCIM resources with exactly the same schema and values as
submitted. SCIM responses SHALL reflect resource state as interpreted
by the SCIM service provider.</t>
</section>
<section anchor="endpoints" title="SCIM Endpoints and HTTP Methods">
<t>The SCIM protocol specifies well-known endpoints and HTTP methods
for managing resources defined in the core schema; i.e., <spanx
style="verb">User</spanx> and <spanx style="verb">Group</spanx>
resources correspond to <spanx style="verb">/Users</spanx> and <spanx
style="verb">/Groups</spanx> respectively. Service providers that
support extended resources SHOULD define resource endpoints using the
convention of pluralizing the resource name defined in the extended
schema by appending an 's'. Given there are cases where resource
pluralization is ambiguous; e.g., a resource named <spanx
style="verb">Person</spanx> is legitimately <spanx style="verb">Persons</spanx>
and <spanx style="verb">People</spanx>, clients SHOULD discover
resource endpoints via the <spanx style="verb">/ResourceTypes</spanx>
endpoint.</t>
<texttable anchor="httpMethods" style="headers"
title="SCIM HTTP Methods">
<ttcol>HTTP Method</ttcol>
<ttcol>SCIM Usage</ttcol>
<c>GET</c>
<c>Retrieves one or more complete or partial resources.</c>
<c>POST</c>
<c>Depending on the endpoint, creates new resources, create a search
request, or MAY be used to bulk modify resources.</c>
<c>PUT</c>
<c>Modifies a resource by replacing existing attributes with a
specified set of replacement attributes (replace). PUT MUST NOT be
used to create new resources.</c>
<c>PATCH</c>
<c>Modifies a resource with a set of client specified changes
(partial update).</c>
<c>DELETE</c>
<c>Deletes a resource.</c>
</texttable>
<texttable anchor="endpoint-summary" style="headers"
title="Defined endpoints">
<ttcol align="left">Resource</ttcol>
<ttcol align="left">Endpoint</ttcol>
<ttcol align="left">Operations</ttcol>
<ttcol align="left">Description</ttcol>
<c>User</c>
<c>/Users</c>
<c><xref format="default" target="get-resource">GET</xref>, <xref
format="default" target="create-resource">POST</xref>, <xref
format="default" target="edit-resource-with-put">PUT</xref>, <xref
format="default" target="edit-resource-with-patch">PATCH</xref>,
<xref format="default" target="delete-resource">DELETE</xref></c>
<c>Retrieve, Add, Modify Users</c>
<c>Group</c>
<c>/Groups</c>
<c><xref format="default" target="get-resource">GET</xref>, <xref
format="default" target="create-resource">POST</xref>, <xref
format="default" target="edit-resource-with-put">PUT</xref>, <xref
format="default" target="edit-resource-with-patch">PATCH</xref>,
<xref format="default" target="delete-resource">DELETE</xref></c>
<c>Retrieve, Add, Modify Groups</c>
<c>Self</c>
<c>/Me</c>
<c><xref target="meAlias">GET, POST, PUT, PATCH, DELETE </xref></c>
<c>Alias for operations against a resource mapped to an
authenticated Subject (e.g., User).</c>
<c>Service Provider Config</c>
<c>/ServiceProvider Config</c>
<c><xref format="default" target="discovery">GET</xref></c>
<c>Retrieve Service Provider's configuration</c>
<c>Resource Type</c>
<c>/ResourceTypes</c>
<c><xref format="default" target="discovery">GET</xref></c>
<c>Retrieve supported resource types</c>
<c>Schema</c>
<c>/Schemas</c>
<c><xref format="default" target="discovery">GET</xref></c>
<c>Retrieve one or more supported schemas.</c>
<c>Bulk</c>
<c>/Bulk</c>
<c><xref format="default" target="bulk-resources">POST</xref></c>
<c>Bulk updates to one or more resources</c>
<c>Search</c>
<c>[prefix]/.search</c>
<c><xref format="default" target="query-post">POST</xref></c>
<c>Search from system root or within a resource endpoint for one or
more resource types using POST.</c>
</texttable>
<t>All requests to the service provider are made via HTTP Methods as
per <xref target="RFC7231">Section 4.3</xref> on a URL derived from
the Base URL. Responses are returned in the body of the HTTP response,
formatted as JSON. Error status codes SHOULD be transmitted via the
HTTP status code of the response (if possible), and SHOULD also be
specified in the body of the response (see <xref
target="http-response-codes"/>).</t>
</section>
<section anchor="create-resource" title="Creating Resources"
toc="default">
<t>To create new resources, clients send HTTP POST requests to the
resource endpoint such as: <spanx style="verb">/Users</spanx> or
<spanx style="verb">/Groups</spanx>, as defined by the associated
resource type endpoint discovery (see <xref target="discovery"/>).</t>
<t>The server SHALL process attributes according to the following
mutability rules:<list style="symbols">
<t>Attributes in the request body, whose mutability is <spanx
style="verb">readOnly</spanx> (see Section 2.2 of <xref
target="I-D.ietf-scim-core-schema"/>), SHALL be ignored.</t>
<t>Attributes whose mutability is <spanx style="verb">readWrite</spanx>(see
Section 2.2 of <xref target="I-D.ietf-scim-core-schema"/>), that
are omitted from the request body, MAY be assumed to be not
asserted by the client. The service provider MAY assign a default
value to non-asserted attributes in the final resource
representation.</t>
<t>Service providers MAY take into account whether a client has
access to all of the resource's attributes when deciding whether
non-asserted attributes should be defaulted. </t>
<t>Clients that intend to override existing or server defaulted
values for attributes MAY specify <spanx style="verb">null</spanx>
for a single-valued attribute or an empty array <spanx
style="verb">[]</spanx> for a multi-valued attribute to clear all
values.</t>
</list></t>
<t>When the service provider successfully creates the new resource, an
HTTP response SHALL be returned with HTTP status <spanx style="verb">201</spanx>
("Created"). The response body SHOULD contain the service provider's
representation of the newly created resource. The URI of the created
resource SHALL included in the HTTP <spanx style="verb">Location</spanx>
header and theHTTP body, a JSON representation <xref
target="RFC7159"/> with the attribute <spanx style="verb">meta.location</spanx>.
Since the server is free to alter and/or ignore POSTed content,
returning the full representation can be useful to the client,
enabling it to correlate the client and server views of the new
resource.</t>
<t>If the service provider determines creation of the requested
resource conflicts with existing resources; e.g., a <spanx
style="verb">User</spanx> resource with a duplicate <spanx
style="verb">userName</spanx>, the service provider MUST return an
HTTP Status 409, with <spanx style="verb">scimType</spanx> error code
of <spanx style="verb">uniqueness</spanx> as per <xref
target="http-response-codes"/>.</t>
<t>In the following example, a client sends a POST request containing
a <spanx style="verb">User</spanx> to the <spanx style="verb">/Users</spanx>
endpoint.</t>
<figure align="left" alt="" height="" suppress-title="false" title=""
width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">POST /Users HTTP/1.1
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName":"bjensen",
"externalId":"bjensen",
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
}
}
</artwork>
</figure>
<t>In response to the example request above, the server signals a
successful creation with an HTTP status code 201 (Created) and returns
a representation of the resource created.</t>
<figure align="left" alt="" height="" suppress-title="false" title=""
width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">HTTP/1.1 201 Created
Content-Type: application/scim+json
Location:
https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1"
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646",
"externalId":"bjensen",
"meta":{
"resourceType":"User",
"created":"2011-08-01T21:32:44.882Z",
"lastModified":"2011-08-01T21:32:44.882Z",
"location":
"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"e180ee84f0671b1\""
},
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
},
"userName":"bjensen"
}
</artwork>
</figure>
<section anchor="resourceTypes" title="Resource Types">
<t>When adding a resource to a specific endpoint, the meta attribute
<spanx style="verb">resourceType</spanx> SHALL be set by the HTTP
service provider to the corresponding resource type for the
endpoint. For example, a POST to the endpoint <spanx style="verb">/Users</spanx>
will set <spanx style="verb">resourceType</spanx> to <spanx
style="verb">User</spanx>, and <spanx style="verb">/Groups</spanx>
will set <spanx style="verb">resourceType</spanx> to <spanx
style="verb">Group</spanx>.</t>
</section>
</section>
<section anchor="get-resources-ops" title="Retrieving Resources"
toc="default">
<t>Resources MAY be retrieved via opaque, unique URLs or via Query
(see <xref target="query-resources"/>). The attributes returned are
defined in the server's attribute schema (see <xref
target="I-D.ietf-scim-core-schema">Section 8.7</xref>) and request
parameters (see <xref target="addtl-retrieval-query-params"/>). By
default, resource attributes returned in a response are those
attributes whose characteristic <spanx style="verb">returned</spanx>
setting is <spanx style="verb">always</spanx> or <spanx style="verb">default</spanx>
(see Section 2.2 of <xref target="I-D.ietf-scim-core-schema"/>). </t>
<section anchor="get-resource" title="Retrieving a known Resource"
toc="default">
<t>To retrieve a known resource, clients send GET requests to the
resource endpoint; e.g., <spanx style="verb">/Users/{id}</spanx> or
<spanx style="verb">/Groups/{id}</spanx>, or <spanx style="verb">/Schemas/{id}</spanx>,
where <spanx style="verb">{id}</spanx> is a resource identifier (for
example the value of the <spanx style="verb">id</spanx>
attribute).</t>
<t>If the resource exists the server responds with HTTP Status code
200 (OK) and includes the result in the body of the response.</t>
<t>The below example retrieves a single User via the <spanx
style="verb">/Users</spanx> endpoint.</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">GET /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
</artwork>
</figure>
<t>The server responds with:</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">HTTP/1.1 200 OK
Content-Type: application/scim+json
Location:
https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"f250dd84f0671c3"
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646",
"externalId":"bjensen",
"meta":{
"resourceType":"User",
"created":"2011-08-01T18:29:49.793Z",
"lastModified":"2011-08-01T18:29:49.793Z",
"location":
"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"f250dd84f0671c3\""
},
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
},
"userName":"bjensen",
"phoneNumbers":[
{
"value":"555-555-8377",
"type":"work"
}
],
"emails":[
{
"value":"bjensen@example.com",
"type":"work"
}
]
}
</artwork>
</figure>
</section>
<section anchor="query-resources" title="Query Resources"
toc="default">
<t>The SCIM protocol defines a standard set of query parameters that
can be used to filter, sort, and paginate to return zero or more
resources in a query response. Queries MAY be made against a single
resource or a resource type endpoint (e.g., <spanx style="verb">/Users</spanx>),
or the service provider Base URI. SCIM service providers MAY support
additional query parameters not specified here and SHOULD ignore any
query parameters they do not recognize instead of rejecting the
query for versioning compatibility reasons.</t>
<t>Responses MUST be identified using the following URI: <spanx
style="verb">urn:ietf:params:scim:api:messages:2.0:ListResponse</spanx>.
The following attributes are defined for responses:</t>
<t><list style="hanging">
<t hangText="totalResults">The total number of results returned
by the list or query operation. The value may be larger than the
number of resources returned such as when returning a single
page (see <xref format="default" target="pagination"/>) of
results where multiple pages are available. REQUIRED.</t>
<t hangText="Resources">A multi-valued list of complex objects
containing the requested resources. This MAY be a subset of the
full set of resources if <xref format="default"
target="pagination">pagination</xref> is requested. REQUIRED if
<spanx style="verb">totalResults</spanx> is non-zero.</t>
<t hangText="startIndex">The 1-based index of the first result
in the current set of list results. REQUIRED when partial
results returned due to pagination.</t>
<t hangText="itemsPerPage">The number of resources returned in a
list response page. REQUIRED when partial results returned due
to pagination.</t>
</list></t>
<t>A query that does not return any matches SHALL return success
(HTTP Status 200) with <spanx style="verb">totalResults</spanx> set
to a value of 0.</t>
<t/>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<preamble>The example query below requests the userName for all
Users:</preamble>
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">GET /Users?attributes=userName
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
</artwork>
</figure>
<t/>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<preamble>The following is an example response to the query
above:</preamble>
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults":2,
"Resources":[
{
"id":"2819c223-7f76-453a-919d-413861904646",
"userName":"bjensen"
},
{
"id":"c75ad752-64ae-4823-840d-ffa80929976c",
"userName":"jsmith"
}
]
} </artwork>
<postamble>Note that in the above example, <spanx style="verb">id</spanx>
is returned because the <spanx style="verb">id</spanx> attribute
has the <spanx style="verb">returned</spanx> characteristic of
<spanx style="verb">always</spanx>.</postamble>
</figure>
<section anchor="query-endpoints" title="Query Endpoints">
<t>Queries MAY be performed against a SCIM resource object, a
resource type endpoint, or a SCIM server root. For example: <list>
<t><spanx style="verb">/Users/{id}</spanx></t>
<t><spanx style="verb">/Users</spanx></t>
<t><spanx style="verb">/Groups</spanx></t>
</list></t>
<t>A query against a server root indicates that all resources
within the server SHALL be included subject to filtering. A filter
expression using <spanx style="verb">meta.resourceType</spanx> MAY
be used to restrict results to one or more specific resource types
(to exclude others). For example:<figure>
<artwork>filter=(meta.resourceType eq User) or (meta.resourceType eq Group)</artwork>
</figure></t>
<t>If a SCIM service provider determines that too many results
would be returned (e.g., because a client queried a resource type
endpoint or the server base URI), the server SHALL reject the
request by returning an HTTP response with <spanx style="verb">status</spanx>
400 and json attribute <spanx style="verb">scimType</spanx> set to
<spanx style="verb">tooMany</spanx> (see <xref
target="scimTypes"/>).</t>
<t>When processing query operations using endpoints that include
more than one SCIM resource type (e.g., a query from the server
root endpoint), filters MUST be processed as outlined in <xref
target="filtering"/>. For filtered attributes that are not part of
a particular resource type, the service provider SHALL treat the
attribute as if there is no attribute value. For example, a
presence or equality filter for an undefined attribute evaluates
as FALSE.</t>
</section>
<section anchor="filtering" title="Filtering">
<t>Filtering is an OPTIONAL parameter for SCIM service providers.
Clients MAY discover service provider filter capabilities by
looking at the <spanx style="verb">filter</spanx> attribute of the
<spanx style="verb">ServiceProviderConfig</spanx> (see <xref
target="discovery"/>). Clients MAY request a subset of resources
by specifying the <spanx style="verb">filter</spanx> query
parameter containing a filter expression. When specified only
those resources matching the filter expression SHALL be returned.
The expression language that is used with the filter parameter
supports references to attributes and literals.</t>
<t>Attribute names and attribute operators used in filters are
case insensitive. For example, the following two expressions will
evaluate to the same logical value:</t>
<figure align="center" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
filter=userName Eq "john"
filter=Username eq "john"
</artwork>
</figure>
<t>The filter parameter MUST contain at least one valid expression
(see <xref target="filter-operator-table"/>). Each expression MUST
contain an attribute name followed by an attribute operator and
optional value. Multiple expressions MAY be combined using a
logical operators (see <xref target="logical-operator-table"/>).
Expressions MAY be grouped together using brackets <spanx
style="verb">(</spanx> and <spanx style="verb">)</spanx> (see
<xref target="grouping-operator-table"/>).</t>
<t>The operators supported in the expression are listed in the
following table.</t>
<texttable align="center" anchor="filter-operator-table"
title="Attribute Operators">
<ttcol align="left">Operator</ttcol>
<ttcol align="left">Description</ttcol>
<ttcol align="left">Behavior</ttcol>
<c>eq</c>
<c>equal</c>
<c>The attribute and operator values must be identical for a
match.</c>
<c>ne</c>
<c>not equal</c>
<c>The attribute and operator values are not identical.</c>
<c>co</c>
<c>contains</c>
<c>The entire operator value must be a substring of the
attribute value for a match.</c>
<c>sw</c>
<c>starts with</c>
<c>The entire operator value must be a substring of the
attribute value, starting at the beginning of the attribute
value. This criterion is satisfied if the two strings are
identical.</c>
<c>ew</c>
<c>ends with</c>
<c>The entire operator value must be a substring of the
attribute value, matching at the end of the attribute value.
This criterion is satisfied if the two strings are
identical.</c>
<c>pr</c>
<c>present (has value)</c>
<c>If the attribute has a non-empty or non-null value, or if it
contains a non-empty node for complex attributes there is a
match.</c>
<c>gt</c>
<c>greater than</c>
<c>If the attribute value is greater than operator value, there
is a match. The actual comparison is dependent on the attribute
type. For string attribute types, this is a lexicographical
comparison and for DateTime types, it is a chronological
comparison. For Integer attributes it is a comparison by numeric
value. Boolean and Binary attributes SHALL cause a failed
response (HTTP Status 400) with scimType of invalidFilter.</c>
<c>ge</c>
<c>greater than or equal</c>
<c>If the attribute value is greater than or equal to the
operator value, there is a match. The actual comparison is
dependent on the attribute type. For string attribute types,
this is a lexicographical comparison and for DateTime types, it
is a chronological comparison. For Integer attributes it is a
comparison by numeric value. Boolean and Binary attributes SHALL
cause a failed response (HTTP Status 400) with scimType of
invalidFilter.</c>
<c>lt</c>
<c>less than</c>
<c>If the attribute value is less than operator value, there is
a match. The actual comparison is dependent on the attribute
type. For string attribute types, this is a lexicographical
comparison and for DateTime types, it is a chronological
comparison. For Integer attributes it is a comparison by numeric
value. Boolean and Binary attributes SHALL cause a failed
response (HTTP Status 400) with scimType of invalidFilter.</c>
<c>le</c>
<c>less than or equal</c>
<c>If the attribute value is less than or equal to the operator
value, there is a match. The actual comparison is dependent on
the attribute type. For string attribute types, this is a
lexicographical comparison and for DateTime types, it is a
chronological comparison. For Integer attributes it is a
comparison by numeric value. Boolean and Binary attributes SHALL
cause a failed response (HTTP Status 400) with scimType of
invalidFilter.</c>
</texttable>
<texttable align="center" anchor="logical-operator-table"
title="Logical Operators">
<ttcol align="left">Operator</ttcol>
<ttcol align="left">Description</ttcol>
<ttcol align="left">Behavior</ttcol>
<c>and</c>
<c>Logical And</c>
<c>The filter is only a match if both expressions evaluate to
true.</c>
<c>or</c>
<c>Logical or</c>
<c>The filter is a match if either expression evaluates to
true.</c>
<c>not</c>
<c>Not function</c>
<c>The filter is a match if the expression evaluates to
false.</c>
</texttable>
<texttable align="center" anchor="grouping-operator-table"
title="Grouping Operators">
<ttcol align="left">Operator</ttcol>
<ttcol align="left">Description</ttcol>
<ttcol align="left">Behavior</ttcol>
<c>( )</c>
<c>Precedence grouping</c>
<c>Boolean expressions MAY be grouped using parentheses to
change the standard order of operations; i.e., evaluate <spanx
style="verb">or</spanx> logical operators before logical <spanx
style="verb">and</spanx> operators.</c>
<c>[ ]</c>
<c>Complex attribute filter grouping</c>
<c>Service providers MAY support complex filters where
expressions MUST be applied to the same value of a parent
attribute specified immediately before the left square bracket
("["). The expression within square brackets ("[" and "]") MUST
be a valid filter expression based upon sub-attributes of the
parent attribute. Nested expressions MAY be used. See examples
below.</c>
</texttable>
<t><figure align="left" anchor="filterABNF"
title="ABNF Specification of SCIM Filters">
<preamble>SCIM filters MUST conform to the following ABNF
<xref target="RFC5234"/> rules as specified below:</preamble>
<artwork align="center">FILTER = attrExp / logExp / valuePath / *1"not" "(" FILTER ")"
valuePath = attrPath "[" valFilter "]"
; FILTER uses sub-attribs of a parent attrPath
valFilter = attrExp / logExp / *1"not" "(" valFilter ")"
attrExp = (attrPath SP "pr") /
(attrPath SP compareOp SP compValue)
logExp = FILTER SP ("and" / "or") SP FILTER
compValue = false / null / true / number / string
; rules from JSON (RFC7159)
compareOp = "eq" / "ne" / "co" /
"sw" / "ew" /
"gt" / "lt" /
"ge" / "le"
attrPath = [URI ":"] ATTRNAME *1subAttr
; SCIM attribute name
; URI is SCIM "schema" URI
ATTRNAME = ALPHA *(nameChar)
nameChar = "-" / "_" / DIGIT / ALPHA
subAttr = "." ATTRNAME
; a sub-attribute of a complex attribute</artwork>
</figure></t>
<t>In the above ABNF rules, the <spanx style="verb">compValue</spanx>
(comparison value) rule is built on JSON Data Interchange format
ABNF rules as specified in <xref target="RFC7159"/>, <spanx
style="verb">DIGIT</spanx> and <spanx style="verb">ALPHA</spanx>
are defined per <xref target="RFC5234">Appendix B.1 of</xref> and,
<spanx style="verb">URI</spanx> is defined per <xref
target="RFC3986">Appendix A of</xref>.</t>
<t>Filters MUST be evaluated using the following order of
operations in order of precedence:<list style="numbers">
<t>Grouping Operators</t>
<t>Logical Operators. Where <spanx style="verb">not</spanx>
takes precedence over <spanx style="verb">and</spanx>, which
takes precedence over <spanx style="verb">or</spanx>.</t>
<t>Attribute Operators</t>
</list></t>
<t>If the specified attribute in a filter expression is a
multi-valued attribute, the filter matches if any of the values of
the specified attribute match the specified criterion; e.g., if a
User has multiple emails values, only one has to match for the
entire User to match. For complex attributes, a fully qualified
Sub-Attribute MUST be specified using standard <xref
format="default" target="attribute-notation">attribute
notation</xref>. For example, to filter by userName the parameter
value is <spanx style="verb">userName</spanx>. To filter by first
name, the parameter value is <spanx style="verb">name.givenName</spanx>.</t>
<t>When applying a comparison (e.g., <spanx style="verb">eq</spanx>)
or presence filter (e.g., <spanx style="verb">pr</spanx>), to a
defaulted attribute the service provider SHALL use the value that
was returned to the client that last created or modified the
attribute. </t>
<t>Providers MAY support additional filter operations if they
choose. Providers MUST decline to filter results if the specified
filter operation is not recognized and return a HTTP 400 error
with a scim error type of <spanx style="verb">invalidFilter</spanx>
and an appropriate human readable response as per <xref
target="http-response-codes"/>. For example, if a client specified
an unsupported operator named 'regex' the service provider should
specify an error response description identifying the client
error; e.g., 'The operator 'regex' is not supported.'</t>
<t>When comparing attributes of type String, the case sensitivity
for String type attributes SHALL be determined by the attribute's
<spanx style="verb">caseExact</spanx> characteristic (see Section
2.2 <xref target="I-D.ietf-scim-core-schema"/>).</t>
<t>Clients MAY query by schema or schema extensions by using a
filter expression including the "schemas" attribute (as shown in
the following figure).</t>
<figure align="left" alt="" anchor="exampleFilters" height=""
suppress-title="false" title="Example Filters" width="">
<preamble>The following are examples of valid filters. Some
attributes (e.g., rooms and rooms.number) are hypothetical
extensions and are not part of SCIM core schema:</preamble>
<artwork align="center" alt="" height="" name="" type=""
width="" xml:space="preserve">filter=userName eq "bjensen"
filter=name.familyName co "O'Malley"
filter=userName sw "J"
filter=urn:ietf:params:scim:schemas:core:2.0:User:userName sw "J"
filter=title pr
filter=meta.lastModified gt "2011-05-13T04:42:34Z"
filter=meta.lastModified ge "2011-05-13T04:42:34Z"
filter=meta.lastModified lt "2011-05-13T04:42:34Z"
filter=meta.lastModified le "2011-05-13T04:42:34Z"
filter=title pr and userType eq "Employee"
filter=title pr or userType eq "Intern"
filter=
schemas eq "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
filter=userType eq "Employee" and (emails co "example.com" or emails
co "example.org")
filter=userType ne "Employee" and not (emails co "example.com" or
emails co "example.org")
filter=userType eq "Employee" and (emails.type eq "work")
filter=userType eq "Employee" and emails[type eq "work" and
value co “@example.com"]
filter=emails[type eq "work" and value co “@example.com"] or
ims[type eq "xmpp" and value co "@foo.com"] </artwork>
</figure>
</section>
<section anchor="sorting" title="Sorting">
<t>Sort is OPTIONAL. Clients MAY discover sort capability by
looking at the <spanx style="verb">sort</spanx> attribute of the
service provider configuration (see <xref target="discovery"/>).
Sorting allows clients to specify the order in which resources are
returned by specifying a combination of sortBy and sortOrder URL
parameters.</t>
<t><list style="hanging">
<t hangText="sortBy">The sortBy parameter specifies the
attribute whose value SHALL be used to order the returned
responses. If the sortBy attribute corresponds to a singular
attribute, resources are sorted according to that attribute's
value; if it's a multi-valued attribute, resources are sorted
by the value of the primary attribute (see <xref
target="I-D.ietf-scim-core-schema">Section 2.4</xref>), if
any, or else the first value in the list, if any. If the
attribute is complex the attribute name must be a path to a
sub-attribute in standard <xref format="default"
target="attribute-notation">attribute notation</xref> ; e.g.,
<spanx style="verb">sortBy=name.givenName</spanx>. For all
attribute types, if there is no data for the specified <spanx
style="verb">sortBy</spanx> value they are sorted via the
<spanx style="verb">sortOrder</spanx> parameter; i.e., they
are ordered last if ascending and first if descending.</t>
<t hangText="sortOrder">The order in which the sortBy
parameter is applied. Allowed values are <spanx style="verb">ascending</spanx>
and <spanx style="verb">descending</spanx>. If a value for
sortBy is provided and no sortOrder is specified, the
sortOrder SHALL default to ascending. String type attributes
are case insensitive by default unless the attribute type is
defined as a case exact string. <spanx style="verb">sortOrder</spanx>
MUST sort according to the attribute type; i.e., for case
insensitive attributes, sort the result using case
insensitive, unicode alphabetic sort order, with no specific
locale implied and for case exact attribute types, sort the
result using case sensitive, Unicode alphabetic sort
order.</t>
</list></t>
</section>
<section anchor="pagination" title="Pagination">
<t>Pagination parameters can be used together to "page through"
large numbers of resources so as not to overwhelm the client or
service provider. Because pagination is not stateful, clients MUST
be prepared to handle inconsistent results. For example, a request
for a list of 10 resources beginning with a startIndex of 1 MAY
return different results when repeated as a resource in the
original result could be deleted or new ones could be added
in-between requests. Pagination parameters and general behavior
are derived from the OpenSearch Protocol <xref
target="OpenSearch"/>.</t>
<t>The following table describes the URL pagination
parameters.</t>
<texttable align="center"
anchor="consumer-pagination-options-table"
title="Pagination Request parameters">
<ttcol align="left">Parameter</ttcol>
<ttcol align="left">Description</ttcol>
<ttcol align="left">Default</ttcol>
<c>startIndex</c>
<c>The 1-based index of the first query result. A value less
than 1 SHALL be interpreted as 1.</c>
<c>1</c>
<c>count</c>
<c>Non-negative Integer. Specifies the desired maximum number of
query results per page; e.g., 10. A negative value SHALL be
interpreted as <spanx style="verb">0</spanx>. A value of <spanx
style="verb">0</spanx> indicates no resource results are to be
returned except for <spanx style="verb">totalResults</spanx>.</c>
<c>None. When specified the service provider MUST NOT return
more results than specified though MAY return fewer results. If
unspecified, the maximum number of results is set by the service
provider.</c>
</texttable>
<t>The following table describes the query response pagination
attributes specified by the service provider.</t>
<texttable align="center"
anchor="response-pagination-options-table"
title="Pagination Response Elements">
<ttcol align="left">Element</ttcol>
<ttcol align="left">Description</ttcol>
<c>itemsPerPage</c>
<c>Non-negative Integer. Specifies the number of query results
returned in a query response page; e.g., 10.</c>
<c>totalResults</c>
<c>Non-negative Integer. Specifies the total number of results
matching the client query; e.g., 1000.</c>
<c>startIndex</c>
<c>The 1-based index of the first result in the current set of
query results; e.g., 1.</c>
</texttable>
<t><figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<preamble>For example, to retrieve the first 10 Users, set the
startIndex to 1 and the count to 10:</preamble>
<artwork align="left" alt="" height="" name="" type=""
width="" xml:space="preserve">
GET /Users?startIndex=1&count=10
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
</artwork>
</figure> <figure align="left" alt="" anchor="listResponse"
height="" suppress-title="false"
title="ListResponse format for returning multiple resources"
width="">
<preamble>The response to the query above returns metadata
regarding paging similar to the following example (actual
resources removed for brevity):</preamble>
<artwork align="left" alt="" height="" name="" type=""
width="" xml:space="preserve">
{
"totalResults":100,
"itemsPerPage":10,
"startIndex":1,
"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"Resources":[{
...
}]
}
</artwork>
</figure> Given the example above, to continue paging set the
startIndex to 11 and re-fetch; i.e.,
/Users?startIndex=11&count=10</t>
</section>
<section anchor="attributesParam" title="Attributes">
<t>The following attributes control which attributes SHALL be
returned with a returned resource. SCIM clients MAY use up to one
of these two OPTIONAL parameters which MUST be supported by SCIM
service providers:<list style="hanging">
<t hangText="attributes">A multi-valued list of strings
indicating the names of resource attributes to return in the
response overriding the set of attributes that would be
returned by default. Attribute names MUST be in standard.<xref
format="default" target="attribute-notation">attribute
notation</xref> form. See <xref format="default"
target="addtl-retrieval-query-params">additional retrieval
query parameters</xref>.</t>
<t hangText="excludedAttributes">A multi-valued list of
strings indicating the names of resource attributes to be
removed from the default set of attributes to return. This
parameter SHALL have no effect on attributes whose schema
<spanx style="verb">returned</spanx> setting is <spanx
style="verb">always</spanx> see <xref
target="I-D.ietf-scim-core-schema">Server Schema</xref>.
Attribute names MUST be in standard <xref format="default"
target="attribute-notation">attribute notation</xref> form.
See <xref format="default"
target="addtl-retrieval-query-params">additional retrieval
query parameters</xref>.</t>
</list></t>
</section>
</section>
<section anchor="query-post"
title="Querying Resources Using HTTP POST">
<t>Clients MAY execute queries without passing parameters on the URL
by using the HTTP POST verb combined with the <spanx style="verb">/.search</spanx>
path extension. The inclusion of <spanx style="verb">/.search</spanx>
on the end of a valid SCIM endpoint SHALL be used to indicate the
HTTP POST verb is intended to be a query operation.</t>
<t>To create a new query result set, a SCIM client sends an HTTP
POST request to the desired SCIM resource endpoint (ending in <spanx
style="verb">/.search</spanx>). The body of the POST request MAY
include any of the parameters as defined in <xref
target="query-resources"/>.</t>
<t>Query requests MUST be identified using the following URI: <spanx
style="verb">urn:ietf:params:scim:api:messages:2.0:SearchRequest</spanx>.
The following attributes are defined for query requests:</t>
<t><list style="hanging">
<t hangText="attributes">A multi-valued list of strings
indicating the names of resource attributes to return in the
response overriding the set of attributes that would be returned
by default. Attribute names MUST be in standard <xref
format="default" target="attribute-notation">attribute
notation</xref> form. See <xref format="default"
target="addtl-retrieval-query-params">additional retrieval query
parameters</xref>. OPTIONAL.</t>
<t hangText="excludedAttributes">A multi-valued list of strings
indicating the names of resource attributes to be removed from
the default set of attributes to return. This parameter SHALL
have no effect on attributes whose schema <spanx style="verb">returned</spanx>
setting is <spanx style="verb">always</spanx> see <xref
target="I-D.ietf-scim-core-schema">Server Schema</xref>.
Attribute names MUST be in standard <xref format="default"
target="attribute-notation">attribute notation</xref> form. See
<xref format="default"
target="addtl-retrieval-query-params">additional retrieval query
parameters</xref>. OPTIONAL.</t>
<t hangText="filter">The filter string used to request a subset
of resources. The filter string MUST be a valid <xref
format="default" target="filtering">filter</xref> expression.
OPTIONAL.</t>
<t hangText="sortBy">A string indicating the attribute whose
value SHALL be used to order the returned responses. The sortBy
attribute MUST be in standard <xref format="default"
target="attribute-notation">attribute notation</xref> form. See
<xref format="default" target="sorting">sorting</xref>.
OPTIONAL.</t>
<t hangText="sortOrder">A string indicating the order in which
the sortBy parameter is applied. Allowed values are "ascending"
and "descending". See <xref format="default"
target="sorting">sorting</xref>. OPTIONAL.</t>
<t hangText="startIndex">An integer indicating the 1-based index
of the first query result. See <xref format="default"
target="pagination">pagination</xref>. OPTIONAL.</t>
<t hangText="count">An integer indicating the desired maximum
number of query results per page. See <xref format="default"
target="pagination">pagination</xref>. OPTIONAL.</t>
</list></t>
<t>After receiving a HTTP POST request, a response is returned as
specified in <xref target="query-resources"/>.</t>
<figure align="left" alt="POST Example" anchor="POSTExample"
title="Example POST Query Request">
<preamble>The following example shows an HTTP POST Query request
with search parameters attributes, filter, and count
included:</preamble>
<artwork align="center" height="13">POST /.search
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
"attributes": ["displayName", "userName"],
"filter":
"displayName sw \"smith\"",
"startIndex": 1,
"count": 10
}</artwork>
</figure>
<t/>
<figure align="left" anchor="ExampleResponse"
title="Example POST Query Response">
<preamble>A query response is shown with the first page of
results. For brevity reasons, only two matches are shown: one User
and one Group.</preamble>
<artwork align="center">HTTP/1.1 200 OK
Content-Type: application/scim+json
Location: https://example.com/.search
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults":100,
"itemsPerPage":10,
"startIndex":1,
"Resources":[
{
"id":"2819c223-7f76-413861904646",
"userName":"jsmith",
"displayName":"Smith, James"
},
{
"id":"c8596b90-7539-4f20968d1908",
"displayName":"Smith Family"
},
...
]
} </artwork>
</figure>
</section>
</section>
<section title="Modifying Resources" toc="default">
<t>Resources can be modified in whole or in part using HTTP <spanx
style="verb">PUT</spanx> or <spanx style="verb">PATCH</spanx>,
respectively. Implementers MUST support <spanx style="verb">PUT</spanx>
as specified in <xref target="RFC7231">Section 4.3</xref>. Resources
such as Groups may be very large hence implementers SHOULD support
HTTP PATCH <xref target="RFC5789"/> to enable partial resource
modifications. Service provider support for HTTP <spanx style="verb">PATCH</spanx>
may be discovered by querying the service provider configuration (see
<xref target="discovery"/>). </t>
<section anchor="edit-resource-with-put" title="Replacing with PUT"
toc="default">
<t>HTTP PUT is used to replace a resource's attributes. For example,
clients that have previously retrieved the entire resource in
advance and revised it, MAY replace the resource using an HTTP PUT.
Because SCIM resource identifiers are assigned by the service
provider, HTTP PUT MUST NOT be used to create new resources.</t>
<t>As the operation intent is to replace all attributes, SCIM
clients MAY send all attributes regardless of each attribute's
mutability. The server will apply attribute by attribute replace
according to the following attribute mutability rules: <list
style="hanging">
<t hangText="readWrite, writeOnly">Any values provided SHALL
replace the existing attribute values.</t>
<t>Attributes whose mutability is <spanx style="verb">readWrite</spanx>,
that are omitted from the request body, MAY be assumed to be not
asserted by the client. The service provider MAY assume any
existing values are to be cleared or the service provider MAY
assign a default value to the final resource representation.
Service providers MAY take into account whether a client has
access to, or understands, all of the resource's attributes when
deciding whether non-asserted attributes SHALL be removed or
defaulted. Clients that want to override a server's defaults MAY
specify <spanx style="verb">null</spanx> for a single-valued
attribute, or an empty array <spanx style="verb">[]</spanx> for
a multi-valued attribute to clear all values.</t>
<t hangText="immutable">If value(s) are already set for the
attribute, the input value(s) MUST match or HTTP status 400
SHOULD be returned with <spanx style="verb">scimType</spanx>
error code <spanx style="verb">mutability</spanx>. If the
service provider has no existing values, the new value(s) SHALL
be applied.</t>
<t hangText="readOnly">Any values provided SHALL be ignored.</t>
</list></t>
<t>If an attribute is <spanx style="verb">required</spanx>, clients
MUST specify the attribute in the PUT request.</t>
<t>Unless otherwise specified, a successful PUT operation returns a
200 OK response code and the entire resource within the response
body, enabling the client to correlate the client's and the service
provider's views of the updated resource. Example:</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
PUT /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646",
"userName":"bjensen",
"externalId":"bjensen",
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara",
"middleName":"Jane"
},
"roles":[],
"emails":[
{
"value":"bjensen@example.com"
},
{
"value":"babs@jensen.org"
}
]
}</artwork>
</figure>
<t/>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<preamble>The service responds with the entire, updated
User:</preamble>
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">HTTP/1.1 200 OK
Content-Type: application/scim+json
ETag: W/"b431af54f0671a2"
Location:
"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646"
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646",
"userName":"bjensen",
"externalId":"bjensen",
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara",
"middleName":"Jane"
},
"emails":[
{
"value":"bjensen@example.com"
},
{
"value":"babs@jensen.org"
}
],
"meta": {
"resourceType":"User",
"created":"2011-08-08T04:56:22Z",
"lastModified":"2011-08-08T08:00:12Z",
"location":
"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"b431af54f0671a2\""
}
} </artwork>
</figure>
</section>
<section anchor="edit-resource-with-patch"
title="Modifying with PATCH" toc="default">
<t>HTTP PATCH is an OPTIONAL server function that enables clients to
update one or more attributes of a SCIM resource using a sequence of
operations to <spanx style="verb">add</spanx>, <spanx style="verb">remove</spanx>,
or <spanx style="verb">replace</spanx> values. Clients may discover
service provider support for PATCH by querying the service provider
configuration (see <xref target="discovery"/>). </t>
<t>The general form of the SCIM patch request is based on JavaScript
Object Notation (JSON) Patch <xref target="RFC6902"/>. One
difference between SCIM patch and JSON patch is that SCIM servers do
not support array indexing and do not support <xref
target="RFC6902"/> operation types relating to array element
manipulation such as <spanx style="verb">move</spanx>.</t>
<t>The body of each request MUST contain the <spanx style="verb">schemas</spanx>
attribute with the URI value of: <spanx style="verb">urn:ietf:params:scim:api:messages:2.0:PatchOp</spanx>.</t>
<t>The body of an HTTP PATCH request MUST contain the attribute
<spanx style="verb">Operations</spanx>, whose value is an array of
one or more patch operations. Each patch operation object MUST have
exactly one "op" member, whose value indicates the operation to
perform and MAY be one of <spanx style="verb">add</spanx>, <spanx
style="verb">remove</spanx>, or <spanx style="verb">replace</spanx>.
The semantics of each operation are defined in the following
sub-sections.</t>
<figure anchor="patchFormat"
title="Example JSON body for SCIM PATCH Request">
<preamble>The following is an example representation of a PATCH
request showing the basic JSON structure
(non-normative):</preamble>
<artwork>{ "schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[
{
"op":"add",
"path":"members",
"value":[
{
"display": "Babs Jensen",
"$ref":
"https://example.com/v2/Users/2819c223...413861904646",
"value": "2819c223-7f76-453a-919d-413861904646"
}
]
},
... + additional operations if needed ...
]
}</artwork>
</figure>
<t>The <spanx style="verb">path</spanx> attribute value is a String
containing an attribute path describing the target of the operation.
The <spanx style="verb">path</spanx> attribute is OPTIONAL for
<spanx style="verb">add</spanx> and <spanx style="verb">replace</spanx>
and is REQUIRED for <spanx style="verb">remove</spanx> operations.
See relevant operation sections below for details.</t>
<figure align="left" anchor="pathABNF" title="SCIM Patch PATH Rule">
<preamble>The <spanx style="verb">path</spanx> attribute is
described by the following ABNF syntax rule:</preamble>
<artwork align="center">PATH = attrPath / valuePath [subAttr]</artwork>
</figure>
<t>The ABNF rules, <spanx style="verb">attrPath</spanx>, <spanx
style="verb">valuePath</spanx>, and <spanx style="verb">subAttr</spanx>
are defined in <xref target="filtering"/>. The <spanx style="verb">valuePath</spanx>
rule allows specific values of a complex, multi-valued attribute to
be selected. <figure align="left" anchor="examplePaths"
title="Example Path Values">
<preamble>Valid examples of <spanx style="verb">path</spanx> are
as follows:</preamble>
<artwork align="center">"path":"members"
"path":"name.familyName"
"path":"addresses[type eq \"work\"]"
"path":"members[value eq
\"2819c223-7f76-453a-919d-413861904646\"]"
"path":"members[value eq
\"2819c223-7f76-453a-919d-413861904646\"].displayName"</artwork>
</figure></t>
<t>Each operation against an attribute MUST be compatible with the
attribute's mutability and schema as defined in the <xref
target="I-D.ietf-scim-core-schema">Section 2.2 and 2.3 of</xref>.
For example, a client MUST NOT modify an attribute that has
mutability <spanx style="verb">readOnly</spanx> or <spanx
style="verb">immutable</spanx>. However, a client MAY <spanx
style="verb">add</spanx> a value to an <spanx style="verb">immutable</spanx>
attribute if the attribute had no previous value. An operation that
is not compatible with an attribute's mutability or schema SHALL
return the appropriate HTTP response status code and a JSON detail
error response as defined in <xref
target="http-response-codes"/>.</t>
<t>The attribute notation rules described in <xref
target="attribute-notation"/> apply for describing attribute paths.
For all operations, the value of the <spanx style="verb">schemas</spanx>
attribute on the SCIM service provider's representation of the
resource SHALL be assumed by default. If one of the PATCH operations
modifies the <spanx style="verb">schemas</spanx> attribute,
subsequent operations SHALL assume the modified state of the <spanx
style="verb">schemas</spanx> attribute. Clients MAY implicitly
modify the <spanx style="verb">schemas</spanx> attribute by adding
(or replacing) an attribute with its fully qualified name including
schema URN. For example, adding the attribute <spanx style="verb">urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber</spanx>,
automatically adds the value <spanx style="verb">urn:ietf:params:scim:schemas:extension:enterprise:2.0:User</spanx>
to the resource's <spanx style="verb">schemas</spanx> attribute.</t>
<t>Each patch operation represents a single action to be applied to
the same SCIM resource specified by the request URI. Operations are
applied sequentially in the order they appear in the array. Each
operation in the sequence is applied to the target resource; the
resulting resource becomes the target of the next operation.
Evaluation continues until all operations are successfully applied
or until an error condition is encountered.</t>
<t>For multi-valued attributes, a patch operation that sets a
value's <spanx style="verb">primary</spanx> sub-attribute to <spanx
style="verb">true</spanx>, SHALL cause the server to automatically
set <spanx style="verb">primary</spanx> to <spanx style="verb">false</spanx>
for any other values in the array.</t>
<t>A patch request, regardless of the number of operations, SHALL be
treated as atomic. If a single operation encounters an error
condition, the original SCIM resource MUST be restored, and a
failure status SHALL be returned.</t>
<t>If a request fails, the server SHALL return an HTTP response
status code and a JSON detail error response as defined in <xref
target="http-response-codes"/>.</t>
<t>On successful completion, the server MUST return either a 200 OK
response code and the entire resource within the response body,
subject to the "attributes" query parameter (see <xref
format="default" target="addtl-retrieval-query-params">Additional
Retrieval Query Parameters</xref>); or the server MAY return a 204
No Content response code and the appropriate response headers for a
successful patch request. The server MUST return a 200 OK if the
"attributes" parameter is specified on the request.</t>
<section anchor="addOp" title="Add Operation">
<t>The <spanx style="verb">add</spanx> operation is used to add a
new attribute value to an existing resource.</t>
<t>The operation MUST contain a <spanx style="verb">value</spanx>
member whose content specifies 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 specified in the
operation's <spanx style="verb">path</spanx>.</t>
<t>The result of the add operation depends upon what the target
location indicated by <spanx style="verb">path</spanx> references:
<list style="symbols">
<t>If omitted, the target location is assumed to be the
resource itself. The <spanx style="verb">value</spanx>
parameter contains a set of attributes to be added to the
resource.</t>
<t>If the target location does not exist, the attribute and
value is added.</t>
<t>If the target location specifies a complex attribute, a set
of sub-attributes SHALL be specified in the <spanx
style="verb">value</spanx> parameter.</t>
<t>If the target location specifies a multi-valued attribute,
a new value is added to the attribute.</t>
<t>if the target location specifies a single-valued attribute,
the existing value is replaced.</t>
<t>If the target location specifies an attribute that does not
exist (has no value), the attribute is added with the new
value.</t>
<t>If the target location exists, the value is replaced.</t>
<t>If the target location already contains the value
specified, no changes SHOULD be made to the resource and a
success response SHOULD be returned. Unless other operations
change the resource, this operation SHALL NOT change the
modify timestamp of the resource.</t>
</list></t>
<t/>
<figure align="left">
<preamble>The following example shows how to add a member to a
group. Some text removed for readability ("..."):</preamble>
<artwork>PATCH /Groups/acbf3ae7-8463-...-9b4da3f908ce
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{ "schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[
{
"op":"add",
"path":"members",
"value":[
{
"display": "Babs Jensen",
"$ref":
"https://example.com/v2/Users/2819c223...413861904646",
"value": "2819c223-7f76-453a-919d-413861904646"
}
]
}
]
}</artwork>
</figure>
<t>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 server responds with either the entire updated Group
or no response body:</t>
<figure>
<artwork>HTTP/1.1 204 No Content
Authorization: Bearer h480djs93hd8
ETag: W/"b431af54f0671a2"
Location:
"https://example.com/Groups/acbf3ae7-8463-...-9b4da3f908ce"</artwork>
</figure>
<figure align="left">
<preamble>The following example shows how to add one or more
attributes to a User resource without using a <spanx
style="verb">path</spanx> attribute.</preamble>
<artwork>PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[{
"op":"add",
"value":{
"emails":[
{
"value":"babs@jensen.org",
"type":"home"
}
],
"nickname":"Babs"
}]
}</artwork>
<postamble>In the above example, an additional value is added to
the multi-valued attribute <spanx style="verb">emails</spanx>.
The second attribute, <spanx style="verb">nickname</spanx> is
added to the User resource. If the resource already had an
existing <spanx style="verb">nickname</spanx>, the value is
replaced per the processing rules above for single-valued
attributes.</postamble>
</figure>
</section>
<section anchor="removeOp" title="Remove Operation">
<t>The <spanx style="verb">remove</spanx> operation removes the
value at the target location specified by the required attribute
<spanx style="verb">path</spanx>. The operation performs the
following functions depending on the target location specified by
<spanx style="verb">path</spanx> : <list style="symbols">
<t>If <spanx style="verb">path</spanx> is unspecified, the
operation fails with HTTP status <spanx style="verb">400</spanx>
and <spanx style="verb">scimType</spanx> of <spanx
style="verb">noTarget</spanx>.</t>
<t>If the target location is a single-value attribute, the
attribute and its associated value is removed and the
attribute SHALL be considered unassigned.</t>
<t>If the target location is a multi-valued attribute and no
filter is specified, the attribute and all values are removed
and the attribute SHALL be considered unassigned.</t>
<t>If the target location is a multi-valued attribute and a
complex filter is specified comparing a <spanx style="verb">value</spanx>,
the values matched by the filter are removed. If after removal
of the selected values, no other values remain, the
multi-valued attribute SHALL be considered unassigned.</t>
<t>If the target location is a complex-multi-valued attribute
and a complex filter is specified based on the attribute's
sub-attributes, the matching records are removed.
Sub-attributes whose values have been removed SHALL be
considered unassigned. If the complex-multi-valued attribute
has no remaining records, the attribute SHALL be considered
unassigned.</t>
</list></t>
<t>If an attribute is removed or becomes unassigned and is defined
as a required attribute or a read-only attribute, the server SHALL
return an HTTP response status code and a JSON detail error
response as defined in <xref target="http-response-codes"/> with a
<spanx style="verb">scimType</spanx> error of <spanx style="verb">mutability</spanx>.</t>
<t>The following example shows how to remove a member from a
group. As 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 to the resource and a success response
should be returned.</t>
<t>Note that server responses have been omitted for the rest of
the PATCH examples.</t>
<figure align="left">
<preamble>Remove a single member from a group. Some text removed
for readability ("..."):</preamble>
<artwork>PATCH /Groups/acbf3ae7-8463-...-9b4da3f908ce
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[{
"op":"remove",
"path":"members[value eq \"2819c223-7f76-...413861904646\"]"
}]
}</artwork>
</figure>
<figure align="left">
<preamble>Remove all members of a group:</preamble>
<artwork>PATCH /Groups/acbf3ae7-8463-...-9b4da3f908ce
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{ "schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[{
"op":"remove","path":"members"
}]
}</artwork>
</figure>
<figure align="left">
<preamble>Removal of a value from a complex-multi-valued
attribute (request headers removed for brevity):</preamble>
<artwork>{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op":"remove",
"path":"emails[type eq \"work\" and value ew \"example.com\"]"
}]
}</artwork>
</figure>
<figure align="left">
<preamble>Example request to remove and add a member. Some text
removed for readability ("..."):</preamble>
<artwork>PATCH /Groups/acbf3ae7-8463-...-9b4da3f908ce
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{ "schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op":"remove",
"path":
"members[value eq\"2819c223...919d-413861904646\"]"
},
{
"op":"add",
"path":"members",
"value": [
{
"display": "James Smith",
"$ref":
"https://example.com/v2/Users/08e1d05d...473d93df9210",
"value": "08e1d05d...473d93df9210"
}
]
}
]
}</artwork>
</figure>
<figure align="left">
<preamble>The following example shows how to replace all the
members of a group with a different members list. Some text
removed for readabilty ("..."):</preamble>
<artwork>PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op":"remove","path":"members"
},
{
"op":"add",
"path":"members",
"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"
}]
}
]
}</artwork>
</figure>
</section>
<section anchor="replaceOp" title="Replace Operation">
<t>The <spanx style="verb">replace</spanx> operation replaces the
value at the target location specified by the <spanx style="verb">path</spanx>.
The operation performs the following functions depending on the
target location specified by <spanx style="verb">path</spanx> :
<list style="symbols">
<t>If the <spanx style="verb">path</spanx> parameter is
omitted, the target is assumed to be the resource itself. In
this case, the <spanx style="verb">value</spanx> attribute
SHALL contain a list of one or more attributes that are to be
replaced.</t>
<t>If the target location is a single-value attribute, the
attributes value is replaced.</t>
<t>If the target location is a multi-valued attribute and no
filter is specified, the attribute and all values are
replaced.</t>
<t>If the target location path specifies an attribute that
does not exist, the service provider SHALL treat the operation
as an "add".</t>
<t>If the target location specifies a complex attribute, a set
of sub-attributes SHALL be specified in the <spanx
style="verb">value</spanx> parameter which replaces any
existing values or adds where an attribute did not previously
exist. Sub-attributes that are not specified in the <spanx
style="verb">value</spanx> parameter are left unchanged.</t>
<t>If the target location is a multi-valued attribute and a
value selection (<spanx style="verb">valuePath</spanx>) filter
is specified that matches one or more values of the
multi-valued attribute, then all matching record values SHALL
be replaced.</t>
<t>If the target location is a complex-multi-valued attribute
with a value selection filter (<spanx style="verb">valuePath</spanx>)
and a specific sub-attribute (e.g., <spanx style="verb">addresses[type eq "work"].streetAddress</spanx>
), the matching sub-attribute of all matching records is
replaced.</t>
<t>If the target location is a multi-valued attribute for
which a value selection filter (<spanx style="verb">valuePath</spanx>)
has been supplied and no record match was made, the service
provider SHALL fail by returning HTTP status <spanx
style="verb">400</spanx>, and a <spanx style="verb">scimType</spanx>
of <spanx style="verb">noTarget</spanx>.</t>
</list></t>
<figure align="left">
<preamble>The following example shows how to replace all the
members of a group with a different members list in a single
replace operation. Some text removed for readability
("..."):</preamble>
<artwork>PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op":"replace",
"path":"members",
"value":[
{
"display": "Babs Jensen",
"$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"
}
]
}]
}</artwork>
</figure>
<figure align="left">
<preamble>The following example shows how to change a User's
entire "work" address using a <spanx style="verb">valuePath</spanx>
filter. Note that by setting <spanx style="verb">primary</spanx>
to <spanx style="verb">true</spanx>, the service provider will
reset primary to <spanx style="verb">false</spanx> for any other
existing values of <spanx style="verb">addresses</spanx>.</preamble>
<artwork>PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op":"replace",
"path":"addresses[type eq \"work\"]",
"value":
{
"type": "work",
"streetAddress": "911 Universal City Plaza",
"locality": "Hollywood",
"region": "CA",
"postalCode": "91608",
"country": "US",
"formatted":
"911 Universal City Plaza\nHollywood, CA 91608 US",
"primary": true
}
}]
}</artwork>
</figure>
<figure align="left">
<preamble>The following example shows how to change a specific
sub-attribute <spanx style="verb">streetAddress</spanx> of
complex attribute <spanx style="verb">emails</spanx> selected by
<spanx style="verb">valuePath</spanx> filter:</preamble>
<artwork>PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op":"replace",
"path":"addresses[type eq \"work\"].streetAddress",
"value":"1010 Broadway Ave"
}]
}</artwork>
</figure>
<figure align="left">
<preamble>The following example shows how to replace all values
of one or more specific attributes of a User resource. Note that
other attributes are unaffected.</preamble>
<artwork>PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op":"replace",
"value":"{
"emails":[
{
"value":"bjensen@example.com",
"type":"work",
"primary":true
},
{
"value":"babs@jensen.org",
"type":"home"
}
],
"nickname":"Babs"
}]
}</artwork>
</figure>
</section>
</section>
</section>
<section anchor="delete-resource" title="Deleting Resources"
toc="default">
<t>Clients request resource removal via DELETE. Service providers MAY
choose not to permanently delete the resource, but MUST return a 404
error code for all operations associated with the previously deleted
resource. Service providers MUST omit the resource from future query
results. In addition the service provider SHOULD NOT consider the
deleted resource in conflict calculation. For example if a User
resource is deleted, a CREATE request for a User resource with the
same userName as the previously deleted resource SHOULD NOT fail with
a 409 error due to userName conflict.</t>
<figure align="left" alt="" height="" suppress-title="false" title=""
width="">
<artwork align="center" alt="" height="" name="" type="" width=""
xml:space="preserve">
DELETE /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Authorization: Bearer h480djs93hd8
If-Match: W/"c310cd84f0281b7"
</artwork>
</figure>
<t>In response to a successful delete, the server SHALL respond with
successful HTTP status 204 (No Content). A non-normative example
response:</t>
<figure align="left" alt="" height="" suppress-title="false" title=""
width="">
<artwork align="center" alt="" height="" name="" type="" width=""
xml:space="preserve">
HTTP/1.1 204 No Content
</artwork>
</figure>
<t>Example: Client attempt to retrieve the previously deleted User</t>
<figure align="left" alt="" height="" suppress-title="false" title=""
width="">
<artwork align="center" alt="" height="" name="" type="" width=""
xml:space="preserve">
GET /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Authorization: Bearer h480djs93hd8
</artwork>
</figure>
<t>Server Response:</t>
<figure align="left" alt="" height="" suppress-title="false" title=""
width="">
<artwork align="center" alt="" height="" name="" type="" width=""
xml:space="preserve">
HTTP/1.1 404 NOT FOUND
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"Errors":[
{
"description":
"Resource 2819c223-7f76-453a-919d-413861904646 not found",
"code":"404"
}
]
}
</artwork>
</figure>
</section>
<section anchor="bulk-resources" title="Bulk Operations" toc="default">
<t>The SCIM bulk operation is an optional server feature that enables
clients to send a potentially large collection of resource operations
in a single request. Support for bulk requests can be discovered by
querying the service provider configuration (see <xref
target="discovery"/>). The body of a a bulk operation contains a set
of HTTP resource operations using one of the API supported HTTP
methods; i.e., POST, PUT, PATCH or DELETE.</t>
<t>Bulk requests are identified using the following schemas URI:
<spanx style="verb">urn:ietf:params:scim:api:messages:2.0:BulkRequest</spanx>.
Bulk responses are identified using the following URI: <spanx
style="verb">urn:ietf:params:scim:api:messages:2.0:BulkResponse</spanx>.
Bulk requests and bulk responses share many attributes. Unless
otherwise specified, each attribute below is present in both bulk
requests and bulk responses.</t>
<t>The following singular attribute is defined in addition to the
common attributes defined in SCIM core schema.</t>
<t><list style="hanging">
<t hangText="failOnErrors"><vspace/>An Integer specifying the
number of errors that the service provider will accept before the
operation is terminated and an error response is returned.
OPTIONAL in a request. Not valid in a response.</t>
</list></t>
<t>The following complex multi-valued attribute is defined in addition
to the common attributes defined in core schema.</t>
<t><list style="hanging">
<t hangText="Operations"><vspace/>Defines operations within a bulk
job. Each operation corresponds to a single HTTP request against a
resource endpoint. REQUIRED. Operations has the following
sub-attributes:<list style="hanging">
<t hangText="method">The HTTP method of the current operation.
Possible values are <spanx style="verb">POST</spanx>, <spanx
style="verb">PUT</spanx>, <spanx style="verb">PATCH</spanx> or
<spanx style="verb">DELETE</spanx>. REQUIRED.</t>
<t hangText="bulkId">The transient identifier of a newly
created resource, unique within a bulk request and created by
the client. The bulkId serves as a surrogate resource id
enabling clients to uniquely identify newly created resources
in the Response and cross reference new resources in and
across operations within a bulk request. REQUIRED when method
is POST.</t>
<t hangText="version">The current resource version. Version
MAY be used if the service provider supports ETags and the
method is PUT, PATCH, or DELETE.</t>
<t hangText="path">The resource's relative path to the SCIM
service provider's root. If the method is POST the value must
specify a resource type endpoint; e.g., /Users or /Groups
whereas all other method values must specify the path to a
specific resource; e.g.,
/Users/2819c223-7f76-453a-919d-413861904646. REQUIRED in a
request.</t>
<t hangText="data">The resource data as it would appear for a
single POST, PUT or PATCH resource operation. REQUIRED in a
request when method is POST, PUT and PATCH.</t>
<t hangText="location">The resource endpoint URL. REQUIRED in
a response, except in the event of a POST failure.</t>
<t hangText="response">The HTTP response body to the specified
request operation. When indicating a response with an HTTP
status other than a 200 series response, the response body
MUST be included. For normal completion, the server MAY elect
to omit the response body.</t>
<t hangText="status">The HTTP response status code to the
requested operation. When indicating an error, the <spanx
style="verb">response</spanx> attribute MUST contain the
detailed error response as per <xref
target="http-response-codes"/>.</t>
</list></t>
</list></t>
<t>If a bulk job is processed successfully the HTTP response code 200
OK MUST be returned, otherwise an appropriate HTTP error code MUST be
returned.</t>
<t>The service provider MUST continue performing as many changes as
possible and disregard partial failures. The client MAY override this
behavior by specifying a value for the <spanx style="verb">failOnErrors</spanx>
attribute. The failOnErrors attribute defines the number of errors
that the service provider should accept before failing the remaining
operations returning the response.</t>
<t>To be able to reference a newly created resource the attribute
bulkId MAY be specified when creating new resources. The <spanx
style="verb">bulkId</spanx> is defined by the client as a surrogate
identifier in a POST operation (see <xref target="bulkids"/>). The
service provider MUST return the same <spanx style="verb">bulkId</spanx>
together with the newly created resource. The <spanx style="verb">bulkId</spanx>
can then be used by the client to map the service provider id with the
<spanx style="verb">bulkId</spanx> of the created resource.</t>
<t>A SCIM service provider MAY elect to optimize a sequence operations
received (e.g., to improve processing performance). When doing so, the
service provider MUST ensure the client's intent is preserved and the
same stateful result is achieved as for non-optimized processing. For
example, before a <spanx style="verb">User</spanx> can be added to a
<spanx style="verb">Group</spanx>, they must first be created.
Processing these requests out of order, might result in a failure to
add the new <spanx style="verb">User</spanx> to the <spanx
style="verb">Group</spanx>.</t>
<section anchor="circularReferences"
title="Circular Reference Processing">
<t>The service provider MUST try to resolve circular cross
references between resources in a single bulk job but MAY stop after
a failed attempt and instead return the status code 409 Conflict.
The following example exhibits the potential conflict.</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
POST /v2/Bulk
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"Operations": [
{
"method": "POST",
"path": "/Groups",
"bulkId": "qwerty",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group A",
"members": [
{
"type": "Group",
"value": "bulkId:ytrewq"
}
]
}
},
{
"method": "POST",
"path": "/Groups",
"bulkId": "ytrewq",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group B",
"members": [
{
"type": "Group",
"value": "bulkId:qwerty"
}
]
}
}
]
}</artwork>
</figure>
<t>If the service provider resolved the above circular references
the following is returned from a subsequent GET request.</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
GET /v2/Groups?filter=displayName sw 'Group'
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
</artwork>
</figure>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 2,
"Resources": [
{
"id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group A",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T18:29:51.135Z",
"location":
"https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"version": "W\/\"mvwNGaxB5SDq074p\""
},
"members": [
{
"value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"$ref":
"https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"type": "Group"
}
]
},
{
"id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group B",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:50.873Z",
"lastModified": "2011-08-01T18:29:50.873Z",
"location":
"https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"version": "W\/\"wGB85s2QJMjiNnuI\""
},
"members": [
{
"value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"$ref":
"https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"type": "Group"
}
]
}
]
}</artwork>
</figure>
</section>
<section anchor="bulkids" title="BulkdId Temporary Identifiers">
<t>A SCIM client can, within one bulk operation, create a new <spanx
style="verb">User</spanx>, a new <spanx style="verb">Group</spanx>
and add the newly created <spanx style="verb">User</spanx> to the
newly created <spanx style="verb">Group</spanx>. In order to add the
new <spanx style="verb">User</spanx> to the <spanx style="verb">Group</spanx>
the client must use the surrogate id attribute, <spanx style="verb">bulkId</spanx>,
to reference the User. The <spanx style="verb">bulkId</spanx>
attribute value must be pre-pended with the literal <spanx
style="verb">bulkId:</spanx>; e.g., if the bulkId is 'qwerty', the
value is <spanx style="verb">bulkId:qwerty</spanx>. The service
provider MUST replace the string <spanx style="verb">bulkId:qwerty</spanx>
with the permanent resource id once created.</t>
<t>To create multiple distinct requests, each with their own <spanx
style="verb">bulkId</spanx>, the SCIM client specifies different
<spanx style="verb">bulkId</spanx> values for each separate
request.</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<preamble>The following example creates a User with the <spanx
style="verb">userName</spanx> 'Alice' and a <spanx style="verb">Group</spanx>
with the <spanx style="verb">displayName</spanx> 'Tour Guides'
with Alice as a member. Notice that each operation has its own
<spanx style="verb">bulkId</spanx> value. However, the second
operation (whose <spanx style="verb">bulkId</spanx> is <spanx
style="verb">ytrewq</spanx>) refers to the <spanx style="verb">bulkId</spanx>
of <spanx style="verb">qwerty</spanx> in order to add Alice to new
'Tour Guides' group.</preamble>
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">POST /v2/Bulk
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"Operations": [
{
"method": "POST",
"path": "/Users",
"bulkId": "qwerty",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "Alice"
}
},
{
"method": "POST",
"path": "/Groups",
"bulkId": "ytrewq",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Tour Guides",
"members": [
{
"type": "User",
"value": "bulkId:qwerty"
}
]
}
}
]
}</artwork>
</figure>
<figure>
<preamble>The service provider returns the following
response:</preamble>
<artwork>HTTP/1.1 200 OK
Content-Type: application/json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [
{
"location":
"https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST",
"bulkId": "qwerty",
"version": "W\/\"4weymrEsh5O6cAEK\"",
"status": {
"code": "201"
}
},
{
"location":
"https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"method": "POST",
"bulkId": "ytrewq",
"version": "W\/\"lha5bbazU3fNvfe5\"",
"status": {
"code": "201"
}
}
]
}</artwork>
<postamble>In the above example, the Alice User resource has an
<spanx style="verb">id</spanx> of <spanx style="verb">92b725cd-9465-4e7d-8c16-01f8e146b87a</spanx>
and the Tour Guides Group has an <spanx style="verb">id</spanx> of
<spanx style="verb">e9e30dba-f08f-4109-8486-d5c6a331660a</spanx>.</postamble>
</figure>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<preamble>A subsequent GET request for the 'Tour Guides' Group
(with an <spanx style="verb">id</spanx> of <spanx style="verb">e9e30dba-f08f-4109-8486-d5c6a331660a</spanx>)
returns the following with Alice's <spanx style="verb">id</spanx>
as the value for the member in the Group 'Tour Guides':</preamble>
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">HTTP/1.1 200 OK
Content-Type: application/scim+json
Location:
https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
ETag: W/"lha5bbazU3fNvfe5"
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
"displayName": "Tour Guides",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T20:31:02.315Z",
"location":
"https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"version": "W\/\"lha5bbazU3fNvfe5\""
},
"members": [
{
"value": "92b725cd-9465-4e7d-8c16-01f8e146b87a",
"$ref":
"https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"type": "User"
}
]
}</artwork>
</figure>
<t>Extensions that include references to other resources MUST be
handled in the same way by the service provider. The following
example uses the bulkId attribute within the enterprise extension
managerId attribute.</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">POST /v2/Bulk
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"Operations": [
{
"method": "POST",
"path": "/Users",
"bulkId": "qwerty",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "Alice"
}
},
{
"method": "POST",
"path": "/Users",
"bulkId": "ytrewq",
"data": {
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"userName": "Bob",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "11250",
"manager": {
"value": "batchId:qwerty"
}
}
}
}
]
}</artwork>
</figure>
</section>
<section title="Response and Error Handling">
<t>The service provider response MUST include the result of all
processed operations. A <spanx style="verb">location</spanx>
attribute that includes the resource's endpoint MUST be returned for
all operations excluding failed POSTs. The status attribute includes
information about the success or failure of one operation within the
bulk job. The attribute status MUST include the code attribute that
holds the HTTP response code that would have been returned if a
single HTTP request would have been used. If an error occurred the
status MUST also include the description attribute containing a
human readable explanation of the error.</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
"status": "201"
</artwork>
</figure>
<t>The following is an example of a status in a failed
operation.</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
"status": "400",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax"
"detail":
"Request is unparsable, syntactically incorrect, or violates schema.",
"status":"400"
}
</artwork>
</figure>
<t>The following example shows how to add, update, and remove a
user. The <spanx style="verb">failOnErrors</spanx> attribute is set
to '1' indicating the service provider should return on the first
error. The POST operation's bulkId value is set to 'qwerty' enabling
the client to match the new User with the returned resource id
'92b725cd-9465-4e7d-8c16-01f8e146b87a'.</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
POST /v2/Bulk
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"failOnErrors":1,
"Operations":[
{
"method":"POST",
"path":"/Users",
"bulkId":"qwerty",
"data":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:User"],
"userName":"Alice"
}
},
{
"method":"PUT",
"path":"/Users/b7c14771-226c-4d05-8860-134711653041",
"version":"W\/\"3694e05e9dff591\"",
"data":{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"b7c14771-226c-4d05-8860-134711653041",
"userName":"Bob"
}
},
{
"method": "PATCH",
"path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"version": "W/\"edac3253e2c0ef2\"",
"data": {[
{
"op": "remove",
"path": "nickName"
},
{
"op": "add",
"path": "userName",
"value": "Dave"
}
]}
},
{
"method":"DELETE",
"path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"version":"W\/\"0ee8add0a938e1a\""
}
]
}</artwork>
</figure>
<t>The service provider returns the following response.</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [
{
"location":
"https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST",
"bulkId": "qwerty",
"version": "W\/\"oY4m4wn58tkVjJxK\"",
"status": "201"
},
{
"location":
"https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT",
"version": "W\/\"huJj29dMNgu3WXPD\"",
"status": "200"
},
{
"location":
"https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH",
"version": "W\/\"huJj29dMNgu3WXPD\"",
"status": "200"
},
{
"location":
"https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE",
"status": "204"
}
]
}</artwork>
</figure>
<t>The following response is returned if an error occurred when
attempting to create the User 'Alice'. The service provider stops
processing the bulk operation and immediately returns a response to
the client. The response contains the error and any successful
results prior to the error.</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [
{
"method": "POST",
"bulkId": "qwerty",
"status": "400",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax"
"detail":
"Request is unparsable, syntactically incorrect, or violates schema.",
"status":"400"
}
}
]
}</artwork>
</figure>
<t>If the <spanx style="verb">failOnErrors</spanx> attribute is not
specified or the service provider has not reached the error limit
defined by the client the service provider will continue to process
all operations. The following is an example in which all operations
failed.</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [
{
"method": "POST",
"bulkId": "qwerty",
"status": "400",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax"
"detail":
"Request is unparsable, syntactically incorrect, or violates schema.",
"status":"400"
}
},
{
"location":
"https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT",
"status": "412",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Failed to update. Resource changed on the server.",
"status":"412"
}
},
{
"location":
"https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH",
"status": "412",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Failed to update. Resource changed on the server.",
"status":"412"
}
},
{
"location":
"https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE",
"status": "404",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Resource does not exist.",
"status":"404"
}
}
]
}</artwork>
</figure>
</section>
<section anchor="bulkMaxOps" title="Maximum Operations">
<t>The service provider MUST define the maximum number of operations
and maximum payload size a client may send in a single request.
These limits MAY be retrieved from the service provider
Configuration (see 'bulk' in <xref
target="I-D.ietf-scim-core-schema">Section 5 and 8.5 of</xref>). If
either limits are exceeded the service provider MUST return the HTTP
response code 413 Request Entity Too Large. The returned response
MUST specify the limit exceeded in the body of the error
response.</t>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<preamble>The following example the client sent a request
exceeding the service provider's max payload size of 1
megabyte:</preamble>
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">POST /v2/Bulk
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: 4294967296
…</artwork>
</figure>
<figure align="left" alt="" height="" suppress-title="false"
title="" width="">
<preamble>In response to the over-sized request, the server
responds with the following error:</preamble>
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">HTTP/1.1 413 Request Entity Too Large
Content-Type: application/scim+json
{
"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],
"status": "413",
"detail":
"The size of the bulk operation exceeds the maxPayloadSize (1048576)."
}</artwork>
</figure>
</section>
</section>
<section anchor="io-format" title="Data Input/Output Formats">
<t>Servers MUST accept requests and be able to respond with JSON
structured responses using UTF-8 encoding <xref target="RFC3629"/>,
UTF-8 SHALL be the default encoding format. Other media types MAY be
supported by service providers but are beyond the scope of this
specification.</t>
<t>Clients using other encodings MUST specify the format in which the
data is submitted via HTTP header <spanx style="verb">Content-Type</spanx>
as specified in <xref target="RFC7231">Section 3.1.1.5</xref> and MAY
specify the desired response data format via an HTTP <spanx
style="verb">Accept</spanx> header ( <xref target="RFC7231">Section
5.3.2</xref> ); e.g., <spanx style="verb">Accept: application/scim+json</spanx>
or via URI suffix; e.g., <figure align="left" alt="" height=""
suppress-title="false" title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
GET /Users/2819c223-7f76-453a-919d-413861904646.scim
Host: example.com
</artwork>
</figure></t>
<t>Service providers MUST support the accept header <spanx
style="verb">Accept: application/scim+json</spanx> and SHOULD support
header <spanx style="verb">Accept: application/json</spanx> both of
which specify JSON documents conforming to <xref target="RFC7159"/>.
The format defaults to <spanx style="verb">application/scim+json</spanx>
if no format is specified.</t>
<t>Singular attributes are encoded as string name-value-pairs in JSON;
e.g.,</t>
<figure>
<artwork>
"attribute": "value"
</artwork>
</figure>
<t>Multi-valued attributes in JSON are encoded as arrays; e.g.,</t>
<figure>
<artwork>
"attributes": [ "value1", "value2" ]
</artwork>
</figure>
<t>Elements with nested elements are represented as objects in JSON;
e.g,</t>
<figure>
<artwork>
"attribute": { "subattribute1": "value1", "subattribute2": "value2" }
</artwork>
</figure>
</section>
<section anchor="addtl-retrieval-query-params"
title="Additional Operation Response Parameters" toc="default">
<t>For any SCIM operation where a resource representation is returned
(e.g., HTTP GET), the attributes returned are defined as the minimum
attribute set plus default attributes set. The minimum set are those
attributes that have their <spanx style="verb">returned</spanx>
characteristic set to <spanx style="verb">always</spanx> (see Section
2.2 of <xref target="I-D.ietf-scim-core-schema"/>). The default
attribute set are those attributes that have the <spanx style="verb">returned</spanx>
characteristic set to <spanx style="verb">default</spanx>.</t>
<t>Clients MAY request a partial resource representation on any
operation that returns a resource within the response by specifying
either of the mutually exclusive URL query parameters <spanx
style="verb">attributes</spanx> or <spanx style="verb">excludedAttributes</spanx>
as follows: <list hangIndent="8" style="hanging">
<t hangText="attributes">When specified the default list of
attributes SHALL be overridden and each resource returned MUST
contain the minimum set of resource attributes and any attributes
or sub-attributes explicitly requested by the <spanx style="verb">attributes</spanx>
parameter. The query parameter attributes value is a comma
separated list of resource attribute names in standard <xref
format="default" target="attribute-notation">attribute
notation</xref> form (e.g., userName, name, emails).</t>
<t hangText="excludedAttributes">When specified, each resource
returned MUST contain the minimal set of resource attributes.
Additionally, the default set of attributes minus those attributes
listed in <spanx style="verb">excludedAttributes</spanx> are also
returned. The query parameter attributes value is a comma
separated list of resource attribute names in standard <xref
format="default" target="attribute-notation">attribute
notation</xref> form (e.g., userName, name, emails).</t>
</list>.</t>
<figure align="left" alt="" height="" suppress-title="false" title=""
width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
</artwork>
</figure>
<t>Giving the response</t>
<figure align="left" alt="" height="" suppress-title="false" title=""
width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
HTTP/1.1 200 OK
Content-Type: application/scim+json
Location:
https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"a330bc54f0671c9"
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646",
"userName":"bjensen"
}
</artwork>
</figure>
</section>
<section anchor="attribute-notation" title="Attribute Notation">
<t>All operations share a common scheme for referencing simple and
complex attributes. In general, attributes are uniquely identified by
prefixing the attribute name with its schema URN separated by a colon
(":") character; e.g., the core User resource attribute 'userName' is
identified as <spanx style="verb">urn:ietf:params:scim:schemas:core:2.0:User:userName</spanx>.
Clients MAY omit core schema attribute URN prefixes but SHOULD fully
qualify extended attributes with the associated schema extension URN
to avoid naming conflicts. For example, the attribute 'age' defined in
<spanx style="verb">urn:ietf:params:scim:schemas:exampleCo:2.0:hr</spanx>
is uniquely identified as <spanx style="verb">urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age</spanx>.
Complex attributes' sub-attributes are referenced via nested, dot
('.') notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For
example, the fully qualified path for a User's givenName is <spanx
style="verb">urn:ietf:params:scim:schemas:core:2.0:User:name.givenName</spanx>
All facets (URN, attribute and Sub-Attribute name) of the fully
encoded Attribute name are case insensitive.</t>
</section>
<section anchor="meAlias"
title=""/Me" Authenticated Subject Alias">
<t>A client MAY use a URL of the form <spanx style="verb"><base-URI>/Me</spanx>
as a URI alias for the User or other resource associated with the
currently authenticated subject for any SCIM operation. A service
provider MAY respond in one of 3 ways: <list style="symbols">
<t>A service provider that does NOT support this feature SHOULD
respond with status 501 (NOT IMPLEMENTED).</t>
<t>A service provider MAY choose to redirect the client using HTTP
status 308 to the resource associated with the authenticated
subject. The client MAY then repeat the request at the indicated
location.</t>
<t>A service provider MAY process the SCIM request directly. In
any response, the HTTP "Location" header MUST be the permanent
location of the aliased resource associated with the authenticated
subject.</t>
</list></t>
<t>When using the SCIM Create Resource command (HTTP POST) with the
<spanx style="verb">/Me</spanx> alias, the desired resourceType being
created is at the discretion of the service provider based on the
authenticated subject (if not anonymous) making the request and any
request body attributes (e.g., <spanx style="verb">schemas</spanx>).
See <xref target="anonymous-considerations"/> for information on
security considerations related to this operation.</t>
</section>
<section anchor="http-response-codes"
title="HTTP Status and Error Response Handling">
<t>The SCIM Protocol uses the HTTP status response status codes
defined in <xref target="RFC7231"> Section 6</xref> to indicate
operation success or failure. In addition to returning a HTTP response
code implementers MUST return the errors in the body of the response
in the client requested format containing the error response and, per
the HTTP specification, human-readable explanations. Error responses
are identified using the following <spanx style="verb">schema</spanx>
URI: <spanx style="verb">urn:ietf:params:scim:api:messages:2.0:Error</spanx>.
The following attributes are defined for a SCIM error response using a
JSON body:<list style="hanging">
<t hangText="status"><vspace blankLines="0"/>The HTTP status code
(see <xref target="RFC7231">Section 6</xref>) expressed as a JSON
String. REQUIRED</t>
<t hangText="scimType"><vspace blankLines="0"/>A SCIM detailed
error keyword. See <xref target="scimTypes"/>. OPTIONAL</t>
<t hangText="detail"><vspace blankLines="0"/>A detailed, human
readable message. OPTIONAL</t>
</list></t>
<t>Implementers SHOULD handle the identified HTTP status codes as
described below.</t>
<texttable anchor="http-error-handling-table"
title="SCIM HTTP Status Code Usage">
<ttcol align="left">Status</ttcol>
<ttcol align="left">Applicability</ttcol>
<ttcol align="left">Suggested Explanation</ttcol>
<c>307 TEMPORARY REDIRECT</c>
<c>GET, POST, PUT, PATCH, DELETE</c>
<c>The client is directed to repeat the same HTTP request at the
location identified. The client SHOULD NOT use the location provided
in the response as a permanent reference to the resource and SHOULD
continue to use the original request URI <xref
target="RFC7231"/>.</c>
<c>308 PERMANENT REDIRECT</c>
<c>GET, POST, PUT, PATCH, DELETE</c>
<c>The client is directed to repeat the same HTTP request at the
location identified. The client SHOULD use the location provided in
the response as the permanent reference to the resource <xref
target="RFC7538"/>.</c>
<c>400 BAD REQUEST</c>
<c>GET, POST, PUT, PATCH, DELETE</c>
<c>Request is unparsable, syntactically incorrect, or violates
schema</c>
<c>401 UNAUTHORIZED</c>
<c>GET, POST, PUT, PATCH, DELETE</c>
<c>Authorization failure. The authorization header is invalid or
missing.</c>
<c>403 FORBIDDEN</c>
<c>GET, POST, PUT, PATCH, DELETE</c>
<c>Operation is not permitted based on the supplied
authorization.</c>
<c>404 NOT FOUND</c>
<c>GET, POST, PUT, PATCH, DELETE</c>
<c>Specified resource (e.g., User) or end-point, does not exist</c>
<c>409 CONFLICT</c>
<c>POST, PUT, PATCH, DELETE</c>
<c>The specified version number does not match the resource's latest
version number or a service provider refused to create a new,
duplicate resource</c>
<c>412 PRECONDITION FAILED</c>
<c>PUT, PATCH,D ELETE</c>
<c>Failed to update as resource {id} changed on the server last
retrieved</c>
<c>413 REQUEST ENTITY TOO LARGE</c>
<c>POST</c>
<c>{"maxOperations": 1000,"maxPayload": 1048576}</c>
<c>500 INTERNAL SERVER ERROR</c>
<c>GET, POST, PUT, PATCH, DELETE</c>
<c>An internal error. Implementers SHOULD provide descriptive
debugging advice</c>
<c>501 NOT IMPLEMENTED</c>
<c>GET, POST, PUT, PATCH, DELETE</c>
<c>Service Provider does not support the request operation; e.g.,
PATCH</c>
</texttable>
<t>For HTTP Status 400 (Bad Request) responses, the following detail
error types are defined:</t>
<texttable anchor="scimTypes"
title="Table of SCIM Detail Error Keyword Values">
<ttcol>scimType</ttcol>
<ttcol>Description</ttcol>
<ttcol>Applicability</ttcol>
<c>invalidFilter</c>
<c>The specified filter syntax was invalid (does not comply with
<xref target="filterABNF"/>) or the specified attribute and filter
comparison combination is not supported.</c>
<c>GET(<xref target="query-resources"/>), POST (Search - <xref
target="query-post"/>), PATCH (Path Filter - <xref
target="edit-resource-with-patch"/>)</c>
<c>tooMany</c>
<c>The specified filter yields many more results than the server is
willing calculate or process. For example, a filter such as <spanx
style="verb">(userName pr)</spanx> by itself would return all
entries with a <spanx style="verb">userName</spanx> and MAY not be
acceptable to the service provider.</c>
<c>GET(<xref target="query-resources"/>), POST (Search - <xref
target="query-post"/>)</c>
<c>uniqueness</c>
<c>One or more of attribute values is already in use or is
reserved.</c>
<c>POST (Create - <xref target="create-resource"/>), PUT (<xref
target="edit-resource-with-put"/>), PATCH (<xref
target="edit-resource-with-patch"/>)</c>
<c>mutability</c>
<c>The attempted modification is not compatible with the target
attributes mutability or current state (e.g., modification of an
immutable attribute with an existing value).</c>
<c>PUT (<xref target="edit-resource-with-put"/>), PATCH (<xref
target="edit-resource-with-patch"/>)</c>
<c>invalidSyntax</c>
<c>The request body message structure was invalid or did not conform
to the request schema.</c>
<c>POST (Search - <xref target="query-resources"/>, Create - <xref
target="create-resource"/>, Bulk - <xref target="bulk-resources"/>),
PUT (<xref target="edit-resource-with-put"/>)</c>
<c>invalidPath</c>
<c>The path attribute was invalid or malformed (see <xref
target="pathABNF"/>).</c>
<c>PATCH (<xref target="edit-resource-with-patch"/>)</c>
<c>noTarget</c>
<c>The specified <spanx style="verb">path</spanx> did not yield an
attribute or attribute value that could be operated on. This occurs
when the specified <spanx style="verb">path</spanx> value contains a
filter that yields no match.</c>
<c>PATCH (<xref target="edit-resource-with-patch"/>)</c>
<c>invalidValue</c>
<c>A required value was missing, or the value specified was not
compatible with the operation or attribute type (see Section 2.2
<xref target="I-D.ietf-scim-core-schema"/>), or resource schema (see
Section 4 <xref target="I-D.ietf-scim-core-schema"/>).</c>
<c>GET (<xref target="query-resources"/>), POST (Create - <xref
target="create-resource"/>, Query - <xref
target="query-resources"/>), PUT (<xref
target="edit-resource-with-put"/>), PATCH (<xref
target="edit-resource-with-patch"/>)</c>
<c>invalidVers</c>
<c>The specified SCIM protocol version is not supported (see <xref
target="api-versioning"/>).</c>
<c>GET (<xref target="query-resources"/>), POST (ALL), PUT (<xref
target="edit-resource-with-put"/>), PATCH (<xref
target="edit-resource-with-patch"/>), DELETE (<xref
target="delete-resource"/>)</c>
<c>sensitive</c>
<c>The specified request cannot be completed due to passing of
sensitive (e.g., personal) information in a request URI. For
example, personal information SHALL NOT be transmitted over request
URIs. See <xref target="sensitiveUri"/>.</c>
<c>GET (<xref target="query-resources"/>).</c>
</texttable>
<t>Note that in the table above (<xref target="scimTypes"/>), the
applicability table applies to the normal HTTP method but MAY apply
within a SCIM Bulk operation (via HTTP POST).</t>
<t>Error example in response to a non-existent GET request.<figure
align="left" alt="" height="" suppress-title="false" title=""
width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">HTTP/1.1 404 NOT FOUND
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
"status": "404"
} </artwork>
</figure></t>
<t>Error example in response to a PUT request.<figure align="left"
alt="" height="" suppress-title="false" title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">HTTP/1.1 400 BAD REQUEST
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"mutability"
"detail":"Attribute 'id' is readOnly",
"status": "400"
} </artwork>
</figure></t>
</section>
<section anchor="api-versioning" title="SCIM Protocol Versioning">
<t>The Base URL MAY be appended with a version identifier as a
separate segment in the URL path. At this time of this specification,
the identifier is 'v2'. If specified, the version identifier MUST
appear in the URL path immediately preceding the resource endpoint and
conform to the following scheme: the character 'v' followed by the
desired SCIM version number; e.g., a version 'v2' User request is
specified as /v2/Users. When specified service providers MUST perform
the operation using the desired version or reject the request. When
omitted service providers SHOULD perform the operation using the most
recent SCIM protocol version supported by the service provider.</t>
</section>
<section anchor="etags" title="Versioning Resources">
<t>The SCIM protocol supports resource versioning via standard HTTP
ETags <xref target="RFC7232"> Section 2.3</xref>. Service providers
MAY support weak ETags as the preferred mechanism for performing
conditional retrievals and ensuring clients do not inadvertently
overwrite each others changes, respectively. When supported, SCIM
ETags MUST be specified as an HTTP header and SHOULD be specified
within the 'version' attribute contained in the resource's 'meta'
attribute.</t>
<figure align="left" alt="" height="" suppress-title="false" title=""
width="">
<preamble>Example create request:</preamble>
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">POST /Users HTTP/1.1
Host: example.com
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName":"bjensen",
"externalId":"bjensen",
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
}
}
</artwork>
</figure>
<figure align="left" alt="" height="" suppress-title="false" title=""
width="">
<preamble>The server responds with an ETag in the response header
and meta structure.</preamble>
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
HTTP/1.1 201 Created
Content-Type: application/scim+json
Location:
https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1"
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646",
"meta":{
"resourceType":"User",
"created":"2011-08-01T21:32:44.882Z",
"lastModified":"2011-08-01T21:32:44.882Z",
"location":
"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"e180ee84f0671b1\""
},
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
},
"userName":"bjensen"
}
</artwork>
</figure>
<t>With the returned ETag, clients MAY choose to retrieve the resource
only if the resource has been modified.</t>
<t>Conditional retrieval example using If-None-Match <xref
target="RFC7233">Section 3.2</xref> header:</t>
<figure align="left" alt="" height="" suppress-title="false" title=""
width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
If-None-Match: W/"e180ee84f0671b1"
</artwork>
</figure>
<t>If the resource has not changed the service provider simply returns
an empty body with a 304 "Not Modified" response code.</t>
<t>If the service providers supports versioning of resources the
client MAY supply an If-Match <xref target="RFC7233">Section
3.2</xref> header for PUT and PATCH operations to ensure that the
requested operation succeeds only if the supplied ETag matches the
latest service provider resource; e.g., If-Match:
W/"e180ee84f0671b1"</t>
</section>
</section>
<section anchor="discovery"
title="Service Provider Configuration Endpoints">
<t>SCIM 2 defines 3 endpoints to facilitate discovery of SCIM service
provider features and schema that MAY be retrieved using HTTP GET:<list
style="hanging">
<t hangText="/ServiceProviderConfig"><vspace/>An HTTP GET to this
endpoint will return a JSON structure that describes the SCIM
specification features available on a service provider. This
endpoint SHALL return responses with a JSON object using a <spanx
style="verb">schemas</spanx> attribute of <spanx style="verb">urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig</spanx>.
The attributes returned in the JSON object are defined in <xref
target="I-D.ietf-scim-core-schema">Section 5</xref>. An example
representation of SCIM service provider configuration may be found
in <xref target="I-D.ietf-scim-core-schema">Section 8.5</xref>.</t>
<t hangText="/Schemas"><vspace/>An HTTP GET to this endpoint is used
to retrieve information about resource schemas supported by a SCIM
service provider. An HTTP GET to the endpoint <spanx style="verb">/Schemas</spanx>
SHALL return all supported schemas in ListResponse format (see <xref
target="listResponse"/>). Individual schema definitions can be
returned by appending the schema URI to the schemas endpoint. For
example:<figure>
<artwork align="center">/Schemas/urn:ietf:params:scim:schemas:core:2.0:User</artwork>
</figure>The contents of each schema returned is described in
<xref target="I-D.ietf-scim-core-schema">Section 7</xref>. An
example representation of SCIM schemas may be found in <xref
target="I-D.ietf-scim-core-schema">Section 8.7</xref>.</t>
<t hangText="/ResourceTypes"><vspace/>An HTTP GET to this endpoint
is used to discover the types of resources available on a SCIM
service provider (e.g., Users and Groups). Each resource type
defines the endpoints, the core schema URI that defines the
resource, and any supported schema extensions. The attributes
defining a resource type can be found in <xref
target="I-D.ietf-scim-core-schema">Section 6</xref>, and an example
representation can be found in <xref
target="I-D.ietf-scim-core-schema">Section 8.6</xref>.</t>
</list></t>
<t>In cases where a request is for a specific <spanx style="verb">ResourceType</spanx>
or <spanx style="verb">Schema</spanx>, the single JSON object is
returned in the same way a single User or Group is retrieved as per
<xref target="get-resource"/>. When returning multiple ResourceTypes or
Schemas, the message form described by <spanx style="verb">urn:ietf:params:scim:api:messages:2.0:ListResponse</spanx>
(ListResponse) form SHALL be used as shown in <xref
target="listResponse"/> and <xref target="resourceTypeJSON"/> below.
Query parameters described in section 3.2 such as, sorting, attributes,
and paging SHALL be ignored. If a <spanx style="verb">filter</spanx> is
provided, the service provider SHOULD respond with HTTP Status 403
(FORBIDDEN) to ensure clients cannot incorrectly assume any matching
conditions specified in a filter are true.</t>
<t><figure anchor="resourceTypeJSON"
title="Example Resource Type JSON Representation">
<preamble>The following is a non-normative example of an HTTP GET to
the /ResourceTypes endpoint:</preamble>
<artwork>{
"totalResults":2,
"itemsPerPage":10,
"startIndex":1,
"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"Resources":[{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
"id":"User",
"name":"User",
"endpoint": "/Users",
"description": "User Account",
"schema": "urn:ietf:params:scim:schemas:core:2.0:User",
"schemaExtensions": [{
"schema":
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"required": true
}],
"meta": {
"location":"https://example.com/v2/ResourceTypes/User",
"resourceType": "ResourceType"
}
},
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
"id":"Group",
"name":"Group",
"endpoint": "/Groups",
"description": "Group",
"schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
"meta": {
"location":"https://example.com/v2/ResourceTypes/Group",
"resourceType": "ResourceType"
}
}]
} </artwork>
</figure></t>
</section>
<section anchor="precis"
title="Preparation and Comparison of Internationalized Strings">
<t>To increase the likelihood that the input and comparison of usernames
and passwords will work in ways that make sense for typical users
throughout the world, there are rules for preparing, enforcing, and
comparing internationalized strings that represent usernames and
passwords. Before comparing or evaluating uniqueness of a <spanx
style="verb">userName</spanx> or <spanx style="verb">password</spanx>
attribute, service providers MUST use the "PRECIS" profile described in
Sections 4 and 5 respectively of <xref
target="I-D.ietf-precis-saslprepbis"/> which is based on the "PRECIS"
framework specification <xref target="I-D.ietf-precis-framework"/>.</t>
</section>
<section anchor="MultiTenancy" title="Multi-Tenancy" toc="default">
<t>A single service provider may expose the SCIM protocol to multiple
clients. Depending on the nature of the service, the clients may have
authority to access and alter resources initially created by other
clients. Alternatively, clients may expect to access disjoint sets of
resources, and may expect that their resources are inaccessible by other
clients. These scenarios are called "multi-tenancy", where each client
is understood to be or represent a "tenant" of the service provider.
Clients may also be multi-tenanted.</t>
<t>The following common cases may occur: <list style="numbers">
<t>All clients share all resources (no tenancy)</t>
<t>Each single client creates and accesses a private subset of
resources (1 client:1 Tenant)</t>
<t>Sets of clients share sets of resources (M clients:1 Tenant)</t>
<t>One client to Multiple Tenants (1 client:M Tenants)</t>
</list> Service providers may implement any subset of the above
cases.</t>
<t>Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a scheme
for multi-tenancy.</t>
<t>The SCIM protocol does not prescribe the mechanisms whereby clients
and service providers interact for: <list style="symbols">
<t>Registering or provisioning Tenants</t>
<t>Associating a subset of clients with a subset of the Tenants</t>
<t>Indicating which tenant is associated with the data in a request
or response, or indicating which Tenant is the subject of a
query</t>
</list></t>
<section anchor="tenantAssoc" title="Associating Clients to Tenants"
toc="default">
<t>The service provider MAY use the authentication mechanism (Section
2) to determine the identity of the client, and thus infer the
associated Tenant.</t>
<t>For implementations where a client is associated with more than one
Tenant, the service provider MAY use one of the following methods for
explicit specification of the Tenant.</t>
<t>If any of these methods of allowing the client to explicitly
specify the Tenant are employed, the service provider should ensure
that access controls are in place to prevent or allow cross-tenant use
cases.</t>
<t>The service provider should consider precedence in cases where a
client may explicitly specify a Tenant while being implicitly
associated with a different Tenant.</t>
<t>In all of these methods, the {tenant_id} is a unique identifier for
the Tenant as defined by the service provider. <list style="symbols">
<t>A URL prefix: <spanx style="verb">https://www.example.com/Tenants/{tenant_id}/v2/Users</spanx></t>
<t>A sub-domain: <spanx style="verb">https://{tenant_id}.example.com/v2/Groups</spanx></t>
<t>The service provider may recognize a {tenant_id} provided by
the client in an HTTP Header as the indicator of the desired
target Tenant.</t>
</list></t>
</section>
<section anchor="tenantIdentifiers"
title="SCIM Identifiers with Multiple Tenants" toc="default">
<t>Considerations for a Multi-Tenant Implementation:</t>
<t>The service provider may choose to implement SCIM ids which are
unique across all resources for all Tenants, but this is not
required.</t>
<t>The externalId, defined by the client, is required to be unique
ONLY within the resources associated with the associated Tenant.</t>
</section>
</section>
<section anchor="Security" title="Security Considerations" toc="default">
<section title="HTTP Considerations">
<t>SCIM Protocol layers on top of Hypertext Transfer Protocol and thus
subject to the security considerations of HTTP <xref
target="RFC7230">Section 9</xref> and its related specifications.</t>
<t>As stated in <xref target="RFC7230">Section 2.7.1</xref>, a SCIM
client MUST NOT generate the <spanx style="verb">userinfo</spanx>
(i.e., username and password) component (and its "@" delimiter) when
an "http" URI reference is generated with a message as they are now
disallowed in HTTP.</t>
</section>
<section title="TLS Support Considerations">
<t>SCIM resources (e.g., Users and Groups) contain sensitive
information including passwords. Therefore, SCIM clients and service
providers MUST require the use of a transport-layer security mechanism
when communicating with SCIM service providers. The SCIM service
provider MUST support TLS 1.2 <xref target="RFC5246"/> and MAY support
additional transport-layer mechanisms meeting its security
requirements. When using TLS, the client MUST perform a TLS/SSL server
certificate check, per <xref target="RFC6125"/>. Implementation
security considerations for TLS can be found in "Recommendations for
Secure Use of TLS and DTLS" <xref target="RFC7525"/>.</t>
</section>
<section title="Authorization Token Considerations">
<t>When using authorization tokens such as those issued by OAuth 2.0
<xref target="RFC6749"/>, implementers MUST take into account threats
and countermeasures documented in Section 8 of <xref
target="I-D.ietf-oauth-assertions"/>.</t>
</section>
<section anchor="bearerConsiderations"
title="Bearer and Cookie Considerations">
<t>Since the possession of a bearer token or cookie MAY authorize the
holder to potentially read, modify, or delete resources, tokens and
cookies MUST contain sufficient entropy to prevent a random guessing
attack, such as described in Section 5.2 of <xref target="RFC6750"/>
and Section 5.1.4.2.2 of <xref target="RFC6819"/>. </t>
<t>As with all SCIM communications, Bearer tokens and HTTP cookies
MUST be exchanged using TLS.</t>
<t>Bearer tokens MUST have a limited lifetime that can be determined
directly or indirectly (e.g., by checking with a validation service)
by the service provider. By expiring tokens, clients are forced to
obtain a new token (which usually involves re-authentication) for
continued authorized access. For example, in OAuth2, a client MAY use
OAuth token refresh to obtain a new bearer token after authenticating
to an authorization server. See Section 6 of <xref
target="RFC6749"/>.</t>
<t>As with Bearer tokens, an HTTP cookie SHOULD last no longer than
the lifetime of a browser session. An expiry time should be set that
limits session cookie lifetime as per Section 5.2.1 of <xref
target="RFC6265"/>. </t>
<t>Implementations supporting OAuth bearer tokens need to factor in
security considerations of this authorization method <xref
target="I-D.ietf-oauth-assertions"/>. Since security is only as good
as the weakest link, implementers also need to consider authentication
choices coupled with OAuth bearer tokens. The security considerations
of the default authentication method for OAuth bearer tokens, HTTP
BASIC, are well documented in <xref
target="I-D.ietf-httpauth-basicauth-update"/>, therefore implementers
are encouraged to prefer stronger authentication methods. Designating
the specific methods of authentication and authorization are
out-of-scope for SCIM, however this information is provided as a
resource to implementers.</t>
</section>
<section title="Privacy Considerations">
<section title="Personal Information">
<t>The SCIM Core Schema specifications defines attributes that may
contain personally identifying information as well as other
sensitive personal data. The privacy considerations in the Security
Considerations Section of <xref target="I-D.ietf-scim-core-schema"/>
MUST be considered.</t>
</section>
<section anchor="sensitiveUri"
title="Disclosure of Sensitive Information in URIs">
<t>As mentioned in <xref target="RFC7231">Section 9.4</xref>, SCIM
clients requesting information using query filters using HTTP GET
SHOULD give consideration to the information content of the filters
and whether their exposure in a URI would represent a breach of
security or confidentiality through leakage in a web browsers or
server logs. This is particularly true for information that is
legally considered "personally identifiable information" or is
otherwise restricted by privacy laws. In these situations to ensure
maximum security and confidentiality, clients SHOULD query using
HTTP POST (see <xref target="query-post"/> ).</t>
<t>Servers that receive HTTP GET requests using filters that contain
sensitive or confidential personal information SHOULD respond with
HTTP status 403 indicating the operation is FORBIDDEN. A <spanx
style="verb">scimType</spanx> error of <spanx style="verb">sensitive</spanx>
may be returned indicating the request must be submitted using POST.
A non-normative example: <figure align="left" alt="" height=""
suppress-title="false" title="" width="">
<artwork align="left" alt="" height="" name="" type="" width=""
xml:space="preserve">
HTTP/1.1 403 FORBIDDEN
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":
"Query filter involving 'name' is restricted or confidential",
"scimType": "sensitive",
"status": "404"
}
</artwork>
</figure></t>
</section>
</section>
<section anchor="anonymous-considerations" title="Anonymous Requests">
<t>If a SCIM service provider accepts anonymous requests such as SCIM
resource creation requests (via HTTP POST), appropriate security
measures should be put in place to prevent or limit exposure to
attacks. The following counter-measures MAY be used:<list
style="symbols">
<t>Try to authenticate web UI components that formulate the SCIM
creation request. While the end-user may be anonymous, the web
user interface component often has its own way to authenticate to
the SCIM service provider (e.g., has an OAuth client credential
<xref target="RFC6749"/>) and the web user interface component may
implement its own measures (e.g., such as CAPTCHA) to ensure a
legitimate request is being made.</t>
<t>Limit the number of requests any particular client MAY make in
a period of time. </t>
<t>For User resources, default newly created resource with an
<spanx style="verb">active</spanx> setting of <spanx style="verb">false</spanx>
and use a secondary confirmation process (e.g., email
confirmation) to ensure the resource created is real.</t>
</list></t>
</section>
<section title="Secure Storage and Handling of Sensitive Data">
<t>An attacker may obtain valid username/password combinations from
the SCIM service provider's underlying database by gaining access to
the database and/or launching injection attacks. This could lead to
unintended disclosure of username/password combinations. The impact
may extend beyond the domain of the SCIM service provider if the data
was provisioned from other domains.</t>
<t>Administrators should undertake industry best practices to protect
the storage of credentials and in particular SHOULD follow
recommendations outlines in Section 5.1.4.1 <xref target="RFC6819"/>.
These recommendations include but are not limited to:<list
style="symbols">
<t>Provide injection attack counter measures (e.g., by validating
all inputs and parameters),</t>
<t>No cleartext storage of credentials,</t>
<t>Store credentials using an encrypted protection mechanism,
and</t>
<t>Avoid passwords and consider use of asymmetric cryptography
based credentials.</t>
</list></t>
<t>As outlined in <xref target="RFC6819">Section 5.1.4.2</xref>,
administrators SHOULD take counter measures to prevent online attacks
on secrets such as:<list style="symbols">
<t>Utilize secure password policy in order to increase user
password entropy to hinder online attacks and password
guessing,</t>
<t>Mitigate attacks on passwords by locking respective accounts
have a number of failed attempts,</t>
<t>Use "tar pit" techniques by temporarily locking a respective
account and delaying responses for a certain duration. The
duration may increase with the number of failed attempts, and</t>
<t>Use authentication system that use CAPTCHA's and other factors
for authenticating users further reducing the possibility of
automated attacks.</t>
</list></t>
<t>Service providers SHOULD define an access control model that
differentiates between individual client applications and their
specific need to access information, and any User self-service rights
to review and update personal profile information. This may include
OAuth 2.0 delegation profiles, that allow client systems to act on
behalf of user's with their permission.</t>
</section>
<section title="Case Insensitive Comparison & International Languages">
<t>When comparing unicode strings such as in query filters or testing
for uniqueness of usernames and passwords, strings MUST be
appropriately prepared before comparison. See <xref
target="precis"/>.</t>
</section>
</section>
<section anchor="IANA" title="IANA Considerations">
<t/>
<section anchor="mediaType" title="Media Type Registration">
<t><list style="hanging">
<t hangText="To:">ietf-types@iana.org</t>
<t hangText="Subject:">Registration of media type
application/scim+json</t>
<t hangText="Type name:">application</t>
<t hangText="Subtype name:">scim+json</t>
<t hangText="Required parameters:">none</t>
<t hangText="Optional parameters:">none</t>
<t hangText="Encoding considerations:">8bit</t>
<t hangText="Security considerations:">See <xref
target="Security"/></t>
<t hangText="Interoperability considerations:">The <spanx
style="verb">application/scim+json</spanx> media type is intended
to identify JSON structure data that conforms to the SCIM protocol
and schema specifications. Older versions of SCIM are known to
informally use <spanx style="verb">application/json</spanx>.</t>
<t hangText="Published specification:">[[this document]]</t>
<t hangText="Applications that use this media type:">It is
expected that applications that use this type may be special
purpose applications intended for inter-domain provisioning.
Clients may also be applications (e.g., mobile applications) that
need to use SCIM for self-registration of user accounts. SCIM
services may be offered by web applications that offer support for
standards based provisioning or may be a dedicated SCIM service
provider such as a "cloud directory". Content may be treated as
equivalent to <spanx style="verb">application/json</spanx> type
for the purpose of displaying in web browsers.</t>
<t hangText="Additional information:"><list>
<t>Magic number(s):</t>
<t>File extension(s): .scim .scm</t>
<t>Macintosh file type code(s):</t>
</list></t>
<t
hangText="Person & email address to contact for further information:">SCIM
mailing list <spanx style="verb"><scim@ietf.org></spanx></t>
<t hangText="Intended usage:">COMMON* (see restrictions)</t>
<t hangText="Restrictions on usage:">For most client types, it is
sufficient to recognize the content as equivalent to <spanx
style="verb">application/json</spanx>. Applications intending to
use SCIM protocol SHOULD use the application/scim+json media
type.</t>
<t hangText="Author:">Phil Hunt</t>
<t hangText="Change controller:">IETF</t>
</list></t>
</section>
<section anchor="scimMessageURIs" title="SCIM Message URI Registry">
<t>As per the IANA SCIM Schema Registry in <xref
target="I-D.ietf-scim-core-schema"/>, the following registers and
extends the SCIM Schema Registry to define SCIM protocol
request/response JSON schema URN identifier prefix of <spanx
style="verb">urn:ietf:params:scim:api:messages:2.0</spanx> which is
part of the URN sub-Namespace for SCIM. There is no specific
associated resource type.</t>
<texttable anchor="scimAPIuris"
title="SCIM Schema URIs for Data Resources">
<ttcol>Schema URI</ttcol>
<ttcol>Name</ttcol>
<ttcol>Reference</ttcol>
<c>urn:ietf:params:scim:api: messages:2.0:ListResponse</c>
<c>List/Query Response</c>
<c>See <xref target="query-resources"/></c>
<c>urn:ietf:params:scim:api: messages:2.0:SearchRequest</c>
<c>POST Query Request</c>
<c>See <xref target="query-post"/></c>
<c>urn:ietf:params:scim:api: messages:2.0:PatchOp</c>
<c>Patch Operation</c>
<c>See <xref target="edit-resource-with-patch"/></c>
<c>urn:ietf:params:scim:api: messages:2.0:BulkRequest</c>
<c>Bulk Operations Request</c>
<c>See <xref target="bulk-resources"/></c>
<c>urn:ietf:params:scim:api: messages:2.0:BulkResponse</c>
<c>Bulk Operations Response</c>
<c>See <xref target="bulk-resources"/></c>
<c>urn:ietf:params:scim:api: messages:2.0:Error</c>
<c>Error Response</c>
<c>See <xref target="http-response-codes"/></c>
</texttable>
</section>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5246.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5789.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.6125.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.6749.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.6750.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7159.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7230.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7232.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7233.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7235.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7538.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-precis-saslprepbis-16.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-scim-core-schema-20.xml'?>
</references>
<references title="Informative References">
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.6265.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.6819.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.6902.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7486.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7525.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-precis-framework-23.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-pop-architecture-01.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-assertions-18.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-httpauth-basicauth-update-07.xml'?>
<reference anchor="XML-Schema">
<front>
<title>XML Schema Part 2: Datatypes Second Edition</title>
<author fullname="Paul V. Biron" initials="P." surname="Biron">
<organization>Kaiser Permanente for Health Level
Seven</organization>
</author>
<author fullname="Ashok Malhotra" initials="A." surname="Malhotra">
<organization>Microsoft (formerly of IBM)</organization>
</author>
<date day="28" month="October" year="2004"/>
</front>
<format target="http://www.w3.org/TR/xmlschema-2/" type="HTML"/>
</reference>
<reference anchor="OpenSearch">
<front>
<title>OpenSearch Protocol 1.1, Draft 5</title>
<author fullname="DeWitt Clinton" initials="D." surname="Clinton">
<organization>A9.org</organization>
</author>
<date month="Dec" year="2005"/>
</front>
<format target="http://www.opensearch.org/Specifications/OpenSearch/1.1"
type="HTML"/>
</reference>
</references>
<section title="Contributors">
<t><list style="empty">
<t>Samuel Erdtman (samuel@erdtman.se)</t>
<t>Patrick Harding (pharding@pingidentity.com)</t>
</list></t>
</section>
<section title="Acknowledgments">
<t>The editors would like to acknowledge the contribution and work of
the past draft editors: <list>
<t>Trey Drake, UnboundID</t>
<t>Chuck Mortimore, Salesforce</t>
</list></t>
<t>The editor would like to thank the participants in the the SCIM
working group for their support of this specification.</t>
</section>
<section title="Change Log">
<t>[[This section to be removed prior to publication as an RFC]]</t>
<t>Draft 02 - KG - Addition of schema extensibility</t>
<t>Draft 03 - PH - Revisions based on following tickets: <list>
<t>24 - Add filter negation</t>
<t>39 - Clarification on response for DELETE</t>
<t>42 - Make root searches optional</t>
<t>49 - Add "ew" filter</t>
<t>50 - Filters for multi-valued complex attributes</t>
<t>51 - Search by Schema</t>
<t>53 - Standard use of term client (some was consumer)</t>
<t>55 - Redirect support (3xx)</t>
<t>56 - Make manager attribute consistent with other $ref attrs</t>
<t>57 - Update all "/v1" examples to '/v2"</t>
<t>59 - Fix capitalization per IETF editor practices</t>
<t>60 - Changed <eref> tags to normal <xref> and
<reference> tags</t>
</list></t>
<t>Draft 04 - PH - Revisions based on the following tickets: <list>
<t>18 - New PATCH command based on JSON Patch (RFC6902)</t>
<t>- Provided ABNF specification for filters (used in PATCH)</t>
<t>- Updated references to RFC4627 to RFC7159</t>
</list></t>
<t>Draft 05 - PH - Revisions based on the following tickets: <list>
<t>03 - Support for excludedAttributes parameter</t>
<t>13 - Change client use of Etags from MUST to MAY (correction)</t>
<t>23 - Clarifications regarding case exact processing.</t>
<t>41 - Add IANA considerations</t>
<t>65 - Removed X-HTTP-Method-Override support</t>
<t>69 - Added clarifications to intro to align with
draft-nottingham-uri-get-off-my-lawn</t>
<t>70 - Remove SCIM_TENANT_ID header</t>
<t>72 - Added text to indicate UTF-8 is default and mandatory
encoding format per BCP18</t>
<t>74 - Added security considerations for using GET with
confidential attribute filters</t>
<t>- corrected error response in JSON PATCH operation</t>
</list></t>
<t>Draft 06 - PH - Revisions based on the following tickets and
editorial changes <list>
<t>41 - Revised content types from application/json to
application/scim+json, registered API schemas</t>
<t>63 - Revised uri schema prefixes for API json message schemas</t>
<t>66 - Updated references for RFC2616 to HTTPbis</t>
<t>75 - Added security considerations for International Strings and
"PRECIS" support</t>
<t>76 - Clarified handling of PUT (& POST) with regards to
mutability and default values</t>
<t>- Corrected version numbers in sec 3.11 API Versioning to v2
(from v1)</t>
<t>- Clarified that no filter matches should return success
totalResults=0</t>
</list></t>
<t>Draft 07 - PH - Revisions regarding support of detailed errors
(Tickets 37, 46, 67)</t>
<t>Draft 08 - PH - Revisions as follows<list>
<t>- Added clarification on schemas handling during PATCH
operation</t>
<t>- Revised example URN in Attribute Notation section to comply
with IANA namespace rules</t>
<t>- Fixed typo in ABNF, attrExpr should be attrExp</t>
<t>- Added more security considerations for HTTP and sensitive
data</t>
<t>- Revised authentication and authorization sections for greater
clarity.</t>
<t>- Replaced the word "search" with "query" for consistency</t>
<t>- Clarified sucessful resource creation response</t>
<t>- Added clarification on primary value handling in PATCH
(consistent with draft 03)</t>
<t>- Revised SCIM Bullk error handling to conform with draft 07
error handling</t>
</list></t>
<t>Draft 09 - PH - Revisions as follows<list>
<t>- Aligned API with new URN namespace per RFC3553 and IETF90
meeting</t>
<t>- Clarified URN usage within patch (what schema urn applies)</t>
<t>- Made 'path' optional in PATCH for Add and Replace</t>
</list></t>
<t>Draft 10 - PH - Revisions as follows<list>
<t>Restructuring of Bulk into sub-sections</t>
<t>General clarifications</t>
<t>Improved Base URI section</t>
<t>Authorization section clarifications</t>
</list></t>
<t>Draft 11 - PH - Revisions as follows<list>
<t>Made mutability processing rules for CREATE more editorially
obvious</t>
<t>Added clarfications and security considerations for Anonymous
operations</t>
<t>Added clarifications to "/Me" for POST requests</t>
<t>Clarified use of bulkids with multiple requests</t>
<t>Corrected JSON parsing issue by adding "Operations" attribute to
PATCH operation</t>
</list></t>
<t>Draft 12 - PH - Editorial NITs <list>
<t>Fix line lengths in artwork to be 72 chars or less</t>
<t>Remove unused references</t>
<t>Fix normative terms per RFC2119</t>
<t>Updated reference to draft-reschke-http-status-308 to RFC7238</t>
</list></t>
<t>Draft 13 - PH - Added clarification to error response for improperly
formated email/phonenumbers</t>
<t>Draft 14 - PH - Nits and clarifications<list>
<t>Added new Service Provider Discovery section that clarifies use
of ResourceTypes, Schemas, and ServiceProviderConfigs</t>
<t>As Complex attributes cannot support sub-attributes that are
complex, the filter ABNF was corrected to prevent nested
valueFilters (which presumes support for nested Complex
Attributes)</t>
<t>Corrections to ABNF: Added missing space (SP) values to logicExp
ABNF rule. Corrected "not(" to make "not" optional.</t>
<t>Added additional filter example showing full path with schema URI
(to disambiguate duplicate names between schemas)</t>
<t>Missing POST verb added to HTTP errors (table 7) since a POST
endpoint might be undefined or NOT FOUND.</t>
<t>Corrected JSON example in sec 3.3.2.1 (removed extraneous " )</t>
<t>Corrected filter in Figure 3 so that multiple resoruce types can
be returned per the response example in figure 4.</t>
<t>Clarifications and improvements to examples in PATCH replace
operations</t>
<t>Updated references to saslprep and precis frameworks</t>
</list></t>
<t>Draft 15 - PH - Clarifications on returning "path" handling during
PATCH "replace" operations. Updated references.</t>
<t>Draft 16 - PH - Clarification of SCIM protocol definitions of
resources vs messages and general process rules regarding schema
including validation.</t>
<t>Draft 17 - PH - Edits based on Gen-ART review</t>
<t>Draft 18 - PH - Edits based on IESG feedback<list>
<t>Clarified use of authentication schemes</t>
<t>Nits and wording clarifications</t>
<t>Corrected definitions of HTTP Status 401/403</t>
<t>Manager corrected in PATCH example operation (consistent with
schema and examples)</t>
<t>Removed editor's note regarding Service Provider unique error
codes</t>
<t>Updated references to SCIM Core Schema and other documents.</t>
<t>Made capitalization of 'client' and 'service provider' terms
consistent (lower case)</t>
<t>Add references to draft-ietf-oauth-assertions-18 and
draft-ietf-httpauth-basicauth-update-07</t>
</list></t>
<t>Draft 19 - PH - IESG review<list>
<t>Corrections as per IESG review comments from Ben Campbell</t>
<t>Corrections as per IESG review comments from Stephen Farrell</t>
<t>Clarified that other media types may be supported</t>
<t>Corrected non-normative (statements of fact) use of 'MAY' to
'may'.</t>
<t>Changed use of SHOULD use security considerations to MUST</t>
<t>Servers that do not support /Me corrected to return 501 instead
of 403</t>
<t>Removed reference to wikipedia and order of operations</t>
<t>General edits to clarify awkward text and typos</t>
</list></t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 08:53:14 |