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

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