draft-ietf-scim-api-18.txt   draft-ietf-scim-api-19.txt 
Network Working Group P. Hunt, Ed. Network Working Group P. Hunt, Ed.
Internet-Draft Oracle Internet-Draft Oracle
Intended status: Standards Track K. Grizzle Intended status: Standards Track K. Grizzle
Expires: November 12, 2015 SailPoint Expires: November 16, 2015 SailPoint
M. Ansari M. Ansari
Cisco Cisco
E. Wahlstroem E. Wahlstroem
Nexus Technology Nexus Technology
C. Mortimore C. Mortimore
Salesforce Salesforce
May 11, 2015 May 15, 2015
System for Cross-Domain Identity Management: Protocol System for Cross-Domain Identity Management: Protocol
draft-ietf-scim-api-18 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 through a standardized service.
Examples include but are not limited to enterprise to cloud service Examples include but are not limited to enterprise to cloud service
providers, and inter-cloud based scenarios. The specification suite providers, and inter-cloud based scenarios. The specification suite
seeks to build upon experience with existing schemas and deployments, seeks to build upon experience with existing schemas and deployments,
placing specific emphasis on simplicity of development and placing specific emphasis on simplicity of development and
skipping to change at page 1, line 48 skipping to change at page 1, line 48
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 12, 2015. This Internet-Draft will expire on November 16, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 29 skipping to change at page 2, line 29
Table of Contents Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3
1.2. Notational Conventions . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . 7 3. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 8
3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 7 3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 8
3.2. SCIM Endpoints . . . . . . . . . . . . . . . . . . . . . 9 3.2. SCIM Endpoints and HTTP Methods . . . . . . . . . . . . . 9
3.3. Creating Resources . . . . . . . . . . . . . . . . . . . 10 3.3. Creating Resources . . . . . . . . . . . . . . . . . . . 10
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 . . . . . . . . . . . . . 13
3.4.2. Query Resources . . . . . . . . . . . . . . . . . . . 14 3.4.2. Query Resources . . . . . . . . . . . . . . . . . . . 14
3.4.3. Querying Resources Using HTTP POST . . . . . . . . . 25 3.4.3. Querying Resources Using HTTP POST . . . . . . . . . 26
3.5. Modifying Resources . . . . . . . . . . . . . . . . . . . 28 3.5. Modifying Resources . . . . . . . . . . . . . . . . . . . 29
3.5.1. Replacing with PUT . . . . . . . . . . . . . . . . . 29 3.5.1. Replacing with PUT . . . . . . . . . . . . . . . . . 29
3.5.2. Modifying with PATCH . . . . . . . . . . . . . . . . 31 3.5.2. Modifying with PATCH . . . . . . . . . . . . . . . . 31
3.6. Deleting Resources . . . . . . . . . . . . . . . . . . . 45 3.6. Deleting Resources . . . . . . . . . . . . . . . . . . . 45
3.7. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 46 3.7. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 46
3.7.1. Circular Reference Processing . . . . . . . . . . . . 48 3.7.1. Circular Reference Processing . . . . . . . . . . . . 48
3.7.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 51 3.7.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 51
3.7.3. Response and Error Handling . . . . . . . . . . . . . 55 3.7.3. Response and Error Handling . . . . . . . . . . . . . 55
3.7.4. Maximum Operations . . . . . . . . . . . . . . . . . 61 3.7.4. Maximum Operations . . . . . . . . . . . . . . . . . 60
3.8. Data Input/Output Formats . . . . . . . . . . . . . . . . 62 3.8. Data Input/Output Formats . . . . . . . . . . . . . . . . 61
3.9. Additional Operation Response Parameters . . . . . . . . 63 3.9. Additional Operation Response Parameters . . . . . . . . 62
3.10. Attribute Notation . . . . . . . . . . . . . . . . . . . 64 3.10. Attribute Notation . . . . . . . . . . . . . . . . . . . 63
3.11. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 64 3.11. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 63
3.12. HTTP Status and Error Response Handling . . . . . . . . . 65 3.12. HTTP Status and Error Response Handling . . . . . . . . . 64
3.13. API Versioning . . . . . . . . . . . . . . . . . . . . . 69 3.13. SCIM Protocol Versioning . . . . . . . . . . . . . . . . 68
3.14. Versioning Resources . . . . . . . . . . . . . . . . . . 69 3.14. Versioning Resources . . . . . . . . . . . . . . . . . . 68
4. Service Provider Configuration Endpoints . . . . . . . . . . 71 4. Service Provider Configuration Endpoints . . . . . . . . . . 70
5. Preparation and Comparison of Internationalized Strings . . . 73 5. Preparation and Comparison of Internationalized Strings . . . 72
6. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 74 6. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 73
6.1. Associating Clients to Tenants . . . . . . . . . . . . . 74 6.1. Associating Clients to Tenants . . . . . . . . . . . . . 73
6.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 75 6.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 74
7. Security Considerations . . . . . . . . . . . . . . . . . . . 75 7. Security Considerations . . . . . . . . . . . . . . . . . . . 74
7.1. HTTP Considerations . . . . . . . . . . . . . . . . . . . 75 7.1. HTTP Considerations . . . . . . . . . . . . . . . . . . . 74
7.2. TLS Support Considerations . . . . . . . . . . . . . . . 76 7.2. TLS Support Considerations . . . . . . . . . . . . . . . 75
7.3. Authorization Token Considerations . . . . . . . . . . . 76 7.3. Authorization Token Considerations . . . . . . . . . . . 75
7.4. Bearer and Cookie Considerations . . . . . . . . . . . . 76 7.4. Bearer and Cookie Considerations . . . . . . . . . . . . 75
7.5. Privacy Considerations . . . . . . . . . . . . . . . . . 77 7.5. Privacy Considerations . . . . . . . . . . . . . . . . . 76
7.5.1. Personal Information . . . . . . . . . . . . . . . . 77 7.5.1. Personal Information . . . . . . . . . . . . . . . . 76
7.5.2. Disclosure of Sensitive Information in URIs . . . . . 77 7.5.2. Disclosure of Sensitive Information in URIs . . . . . 76
7.6. Anonymous Requests . . . . . . . . . . . . . . . . . . . 78 7.6. Anonymous Requests . . . . . . . . . . . . . . . . . . . 77
7.7. Secure Storage and Handling of Sensitive Data . . . . . . 78 7.7. Secure Storage and Handling of Sensitive Data . . . . . . 77
7.8. Case Insensitive Comparison & International Languages . . 79 7.8. Case Insensitive Comparison & International Languages . . 78
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 78
8.1. Media Type Registration . . . . . . . . . . . . . . . . . 79 8.1. Media Type Registration . . . . . . . . . . . . . . . . . 78
8.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 81 8.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 79
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 81 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 80
9.1. Normative References . . . . . . . . . . . . . . . . . . 81 9.1. Normative References . . . . . . . . . . . . . . . . . . 80
9.2. Informative References . . . . . . . . . . . . . . . . . 83 9.2. Informative References . . . . . . . . . . . . . . . . . 82
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 84 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 83
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 84 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 83
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 84 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 protocol for
provisioning and managing identity data on the web and in cross- provisioning and managing identity data on the web and in cross-
domain environments such as enterprise to cloud, or inter-cloud domain environments such as enterprise to cloud, or inter-cloud
scenarios. The protocol supports creation, modification, retrieval, scenarios. The protocol supports creation, modification, retrieval,
and discovery of core identity resources such as Users and Groups, as and discovery of core identity resources such as Users and Groups, as
well as custom resources and resource extensions. well as custom resources and resource extensions.
skipping to change at page 4, line 20 skipping to change at page 4, line 20
keywords are capitalized when used to unambiguously specify keywords are capitalized when used to unambiguously specify
requirements of the protocol or application features and behavior requirements of the protocol or application features and behavior
that affect the interoperability and security of implementations. that affect the interoperability and security of implementations.
When these words are not capitalized, they are meant in their When these words are not capitalized, they are meant in their
natural-language sense. natural-language sense.
For purposes of readability examples are not URL encoded. For purposes of readability examples are not URL encoded.
Implementers MUST percent encode URLs as described in Section 2.1 of Implementers MUST percent encode URLs as described in Section 2.1 of
[RFC3986]. [RFC3986].
Throughout this documents all figures MAY contain spaces and extra Throughout this documents all figures may contain spaces and extra
line-wrapping for readability and space limitations. Similarly, some line-wrapping for readability and space limitations. Similarly, some
URI's contained within examples, have been shortened for space and URI's contained within examples, have been shortened for space and
readability reasons. readability reasons.
1.3. Definitions 1.3. Definitions
This specification uses the definitions from This specification uses the definitions from
[I-D.ietf-scim-core-schema], and defines the following additional [I-D.ietf-scim-core-schema], and defines the following additional
terms: terms:
skipping to change at page 4, line 42 skipping to change at page 4, line 42
The SCIM HTTP protocol is described in terms of a path relative to The SCIM HTTP protocol is described in terms of a path relative to
a Base URI. The Base URI MUST NOT contain a query string as a Base URI. The Base URI MUST NOT contain a query string as
clients MAY append additional path information and query clients MAY append additional path information and query
parameters as part of forming the request. The base URI most parameters as part of forming the request. The base URI most
often is a URL which most often consists of the "https" protocol often is a URL which most often consists of the "https" protocol
scheme, a domain name and some initial path [RFC3986]. Example: scheme, a domain name and some initial path [RFC3986]. Example:
"https://example.com/scim/" "https://example.com/scim/"
For readability, all examples in this document are expressed For readability, all examples in this document are expressed
assuming the SCIM service root and the server root are the same assuming the SCIM service root and the server root are the same
(no path pre-fix). It is expected that SCIM servers MAY be (no path pre-fix). It is expected that SCIM servers may be
deployed using any URI path prefix. For example, a SCIM server deployed using any URI path prefix. For example, a SCIM server
might be have a prefix of "https://example.com/", or might be have a prefix of "https://example.com/", or
"https://example.com/scim/tenancypath/". Additionally a client "https://example.com/scim/tenancypath/". Additionally a client
MAY also apply a version number to the server root prefix (see MAY also apply a version number to the server root prefix (see
Section 3.13 ). Section 3.13 ).
2. Authentication and Authorization 2. Authentication and Authorization
SCIM Protocol is based upon HTTP and does not itself define a SCIM SCIM Protocol is based upon HTTP and does not itself define a SCIM
specific scheme for authentication and authorization. SCIM depends specific scheme for authentication and authorization. SCIM depends
on the use of TLS and/or standard HTTP authentication and on the use of TLS and/or standard HTTP authentication and
authorization schemes as per [RFC7235]. For example, the following authorization schemes as per [RFC7235]. For example, the following
methodologies could be used among others: 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 [RFC5246].
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. See Section 7.4 for and/or OAuth clients SHOULD NOT be used, unless for example, they
security considerations regarding the use of bearer tokens in are being used as single-use tokens to permit one-time requests
SCIM. While bearer tokens most often represent an authorization, such as anonymous registration (see Section 3.3). For security
it is assumed that the authorization was based upon a successful considerations regarding the use of bearer tokens in SCIM see
authentication of the SCIM client. Accordingly the SCIM service Section 7.4. While bearer tokens most often represent an
provider must have a method for validating, parsing, and or authorization, it is assumed that the authorization was based upon
introspecting the bearer token for the relevant authentication and a successful authentication of the SCIM client. Accordingly the
authorization information. The method for this is assumed to be SCIM service provider must have a method for validating, parsing,
defined by the token issuing system and is beyond the scope of and or introspecting the bearer token for the relevant
this specification. authentication and authorization information. The method for this
is assumed to be defined by the token issuing system and is beyond
the scope of this specification.
POP Tokens POP Tokens
A proof-of-possession token demonstrates the presenter of the A proof-of-possession token demonstrates the presenter of the
token possesses a particular key and that the recipient can 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-key. See OAuth 2.0 Proof-of-
Possession Security Architecture [I-D.ietf-oauth-pop-architecture] Possession Security Architecture [I-D.ietf-oauth-pop-architecture]
for an example of such a token and its use. for an example of such a token and its use.
skipping to change at page 6, line 25 skipping to change at page 6, line 28
[I-D.ietf-httpauth-basicauth-update], and therefore implementers [I-D.ietf-httpauth-basicauth-update], and therefore implementers
are encouraged to prefer stronger authentication methods. are encouraged to prefer stronger authentication methods.
Designating the specific methods of authentication and Designating the specific methods of authentication and
authorization are 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 "WWW-
Authenticate" header. Authenticate" header.
For all of the above methodologies, the SCIM service provider MUST be Regardless of methodology, the SCIM service provider MUST be able to
able to map the authenticated client to an access control policy in map the authenticated client to an access control policy in order to
order to determine the client's authorization to retrieve and update determine the client's authorization to retrieve and update SCIM
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 is 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 the action is appropriate
given the subject and the resource affected by the request. The given the subject and the resource affected by the request. The
subject performing the request is usually determined directly or subject performing the request is usually determined directly or
indirectly from the "Authorization" header present in the request. indirectly from the "Authorization" header present in the request.
For example, a subject MAY be permitted to retrieve and update their For example, a subject MAY be permitted to retrieve and update their
own "User" resource, but will normally have restricted ability to own "User" resource, but will normally have restricted ability to
access resources associated with other Users. In other cases, the access resources associated with other Users. In other cases, the
SCIM service provider might only grant access to a subject's own SCIM service provider might only grant access to a subject's own
associated "User" resource (e.g., for the purpose of updating associated "User" resource (e.g., for the purpose of updating
personal contact attributes). personal contact attributes).
For illustrative purposes only, examples show an OAuth2 bearer token For illustrative purposes only, SCIM protocol examples show an OAuth2
value [RFC6750] in the authorization header; e.g., 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 proof-of-possession tokens that represent
an authorization grant such as issued by OAuth (see [RFC6749]), an authorization grant such as 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
skipping to change at page 7, line 20 skipping to change at page 7, line 24
When using bearer tokens or proof-of-possession tokens that represent When using bearer tokens or proof-of-possession tokens that represent
an authorization grant such as issued by OAuth (see [RFC6749]), an authorization grant such as 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 the OAuth
Assertions draft [I-D.ietf-oauth-assertions], documents common Assertions draft [I-D.ietf-oauth-assertions], documents common
scenarios for authorization including: scenarios for authorization including:
o Clients using an assertion to authenticate and/or act on behalf of o Clients using an assertion to authenticate and/or act on behalf of
itself itself;
o Clients acting on behalf of a user. o Clients 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 (e.g., see next
section). section).
Implementers SHOULD take into account the threats and countermeasures When using OAuth authorization tokens, implementers MUST take into
documented in the security considerations for the use of client account the threats and countermeasures documented in the security
authorizations see Section 8 of [I-D.ietf-oauth-assertions]. considerations for the use of client authorizations (see Section 8 of
[I-D.ietf-oauth-assertions]). When using other token formats or
frameworks, implementers MUST take into account similar threats and
countermeasures, especially those documented by the relevant
specifications.
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 self-
registration request where the service provider chooses to accept a registration request where the service provider chooses to accept a
SCIM Create request (see Section 3.3) from an anonymous client. See SCIM Create request (see Section 3.3) from an anonymous client. See
Section 7.6, for security considerations regarding anonymous Section 7.6, for security considerations regarding anonymous
requests. requests.
skipping to change at page 8, line 5 skipping to change at page 8, line 18
SCIM is a protocol that is based on HTTP protocol [RFC7230]. Along SCIM is a protocol that is based on HTTP protocol [RFC7230]. Along
with HTTP headers and URIs, SCIM uses JSON [RFC7159] payloads to with HTTP headers and URIs, SCIM uses JSON [RFC7159] payloads to
convey both SCIM resources, as well as protocol specific payload convey both SCIM resources, as well as protocol specific payload
messages that convey request parameters and response information such messages that convey request parameters and response information such
as errors. Both resources and messages are passed in the form of as errors. Both resources and messages are passed in the form of
JSON based structures in the message body of an HTTP request or JSON based structures in the message body of an HTTP request or
response. To identify this content, SCIM uses a media type of response. To identify this content, SCIM uses a media type of
"application/scim+json" (see Section 8.1). "application/scim+json" (see Section 8.1).
A SCIM "resource" is a JSON object that MAY be created, maintained, A SCIM "resource" is a JSON object [RFC7159] that may be created,
and retrieved through HTTP request methods as described in this maintained, and retrieved through HTTP request methods as described
document. Each JSON resource representation contains a "schemas" in this document. Each JSON resource representation contains a
attribute that contains a list of one or more URIs that indicate "schemas" attribute that contains a list of one or more URIs that
included SCIM schemas that are used to indicate the attributes indicate included SCIM schemas that are used to indicate the
contained within a resource. Specific information about what attributes contained within a resource. Specific information about
attributes are defined within a schema MAY be obtained by querying a what attributes are defined within a schema MAY be obtained by
SCIM service provider's "/Schemas" endpoint for a schema definition querying a SCIM service provider's "/Schemas" endpoint for a schema
(see Section 8.7 [I-D.ietf-scim-core-schema]). Responses from this definition (see Section 8.7 [I-D.ietf-scim-core-schema]). Responses
endpoint describe how a service provider supports a schema and in from this endpoint describe how a service provider supports a schema
particular how attribute qualities such as cardinality, case- and in particular how attribute qualities such as cardinality, case-
exactness, mutability, uniqueness, returnability, and whether an exactness, mutability, uniqueness, returnability, and whether an
attribute is required. While SCIM schemas and associated extension attribute is required. While SCIM schemas and associated extension
model are defined in [I-D.ietf-scim-core-schema], SCIM clients should model are defined in [I-D.ietf-scim-core-schema], SCIM clients should
expect that some attribute schema MAY change from service provider to expect that some attribute schema may change from service provider to
service provider, particularly across administrative domains. In service provider, particularly across administrative domains. In
cases where SCIM MAY be used as an open protocol in front of an cases where SCIM may be used as an open protocol in front of an
application service, it is quite reasonable to expect that some application service, it is quite reasonable to expect that some
service providers MAY only support a sub-set of the schema defined in service providers may only support a sub-set of the schema defined in
[I-D.ietf-scim-core-schema]. [I-D.ietf-scim-core-schema].
A SCIM message conveys protocol parameters about a SCIM request or A SCIM message conveys protocol parameters about a SCIM request or
response that are defined by this specification. As with a SCIM response that are defined by this specification. As with a SCIM
resource, a SCIM message is a JSON object that contains a "schemas" resource, a SCIM message is a JSON object [RFC7159] that contains a
attribute with a URI whose namespace prefix that MUST begin with "schemas" attribute with a URI whose namespace prefix that MUST begin
"urn:ietf:params:scim:api:". As SCIM protocol messages are fixed and with "urn:ietf:params:scim:api:". As SCIM protocol messages are
defined by SCIM specifications and registered extensions, SCIM fixed and defined by SCIM specifications and registered extensions,
message schemas using the above prefix URN SHALL NOT be discoverable SCIM message schemas using the above prefix URN SHALL NOT be
using the "/Schemas" endpoint. discoverable using the "/Schemas" endpoint.
As SCIM is intended for use within cross-domain environments where As SCIM is intended for use in cross-domain scenarios where schema
schema and implementations MAY vary, techniques such as document and implementations may vary, techniques such as document validation,
validation, such as in [XML-Schema], are not recommended. A SCIM such as in [XML-Schema], are not recommended. A SCIM service
service provider interprets a request in the context of its own provider interprets a request in the context of its own schema (which
schema (which MAY be different from the client's schema) and may be different from the client's schema) and following the defined
following the defined processing rules for each request. The processing rules for each request. The following sections in this
following sections in this document define the processing rules for document define the processing rules for SCIM and provide allowances
SCIM and provide allowances for schema differences where appropriate. for schema differences where appropriate. For example, in a SCIM PUT
For example, in a SCIM PUT request, "readOnly" attributes are request, "readOnly" attributes are ignored, while "readWrite"
ignored, while "readWrite" attributes are updated. There is no need attributes are updated. There is no need for a SCIM client to
for a SCIM client to discover which attributes are "readOnly" and discover which attributes are "readOnly" and the client does not need
does not need to remove them from a PUT request in advance in order to remove them from a PUT request in order to be accepted. Similarly
to be accepted. Similarly a SCIM client SHOULD NOT expect a service a SCIM client SHOULD NOT expect a service provider to return SCIM
provider to return SCIM resources with exactly the same schema and resources with exactly the same schema and values as submitted. SCIM
values as submitted. SCIM responses SHALL reflect resource state as responses SHALL reflect resource state as interpreted by the SCIM
interpreted by the SCIM service provider. service provider.
3.2. SCIM Endpoints 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 core schema; i.e., "User" and
"Group" resources correspond to "/Users" and "/Groups" respectively. "Group" resources correspond to "/Users" and "/Groups" respectively.
Service providers that support extended resources SHOULD define Service providers that support extended resources SHOULD define
resource endpoints using the convention of pluralizing the resource resource endpoints using the convention of pluralizing the resource
name defined in the extended schema by appending an 's'. Given there name defined in the extended schema by appending an 's'. Given there
are cases where resource pluralization is ambiguous; e.g., a resource are cases where resource pluralization is ambiguous; e.g., a resource
named "Person" is legitimately "Persons" and "People". Clients named "Person" is legitimately "Persons" and "People", clients SHOULD
SHOULD discover resource endpoints via the "/ResourceTypes" endpoint. discover resource endpoints via the "/ResourceTypes" endpoint.
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.
PUT
Modifies a resource by replacing existing attributes with a
specified set of replacement attributes (replace). PUT MUST NOT
be used to create new resources.
PATCH HTTP SCIM Usage
Modifies a resource with a set of client specified changes Method
(partial update). ------ --------------------------------------------------------------
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.
PUT Modifies a resource by replacing existing attributes with a
specified set of replacement attributes (replace). PUT MUST
NOT be used to create new resources.
PATCH Modifies a resource with a set of client specified changes
(partial update).
DELETE Deletes a resource.
DELETE Table 1: SCIM HTTP Methods
Deletes a resource.
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, Group /Groups GET (Section 3.4.1), Retrieve, Add,
POST (Section 3.3), Modify Groups POST (Section 3.3), Modify Groups
skipping to change at page 10, line 39 skipping to change at page 10, line 39
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 1: 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 [RFC7231] on a URL derived from the Base URL. Responses
are returned in the body of the HTTP response, formatted as JSON. are returned in the body of the HTTP response, formatted as JSON.
Error status codes SHOULD be transmitted via the HTTP status code of Error status codes SHOULD be transmitted via the HTTP status code of
the response (if possible), and SHOULD also be specified in the body the response (if possible), and SHOULD also be specified in the body
of the response (see Section 3.12). 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". resource endpoint such as: "/Users" or "/Groups", as defined by the
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 For attributes in the request body, whose mutability is o Attributes in the request body, whose mutability is "readOnly"
"readOnly", SHALL be ignored. (see Section 2.2 of [I-D.ietf-scim-core-schema]), SHALL be
ignored.
o For attributes whose mutability is "readWrite", that are omitted o Attributes whose mutability is "readWrite"(see Section 2.2 of
from the request body, MAY be assumed to be not asserted by the [I-D.ietf-scim-core-schema]), that are omitted from the request
client. The service provider MAY assign a default value to non- body, MAY be assumed to be not asserted by the client. The
asserted attributes in the final resource representation. service provider MAY assign a default value to non-asserted
attributes in the final resource representation.
o Service providers MAY take into account whether a client has o Service providers MAY take into account whether a client has
access to, or understands, all of the resource's attributes when access to all of the resource's attributes when deciding whether
deciding whether non-asserted attributes should be defaulted. non-asserted attributes should be defaulted.
Clients that intend to override server defaulted values for
attributes MAY specify "null" for a single-valued attribute or an o Clients that intend to override existing or server defaulted
empty array "[]" for a multi-valued attribute to clear all values. values for attributes MAY specify "null" for a single-valued
attribute or an empty array "[]" for a multi-valued attribute to
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 "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 in JSON resource SHALL included in the HTTP "Location" header and theHTTP
resource representation under the attribute "meta.location". Since body, a JSON representation [RFC7159] with the attribute
the server is free to alter and/or ignore POSTed content, returning "meta.location". Since the server is free to alter and/or ignore
the full representation can be useful to the client, enabling it to POSTed content, returning the full representation can be useful to
correlate the client and server views of the new resource. the client, enabling it to correlate the client and server views of
the new resource.
If the service provider determines creation of the requested resource If the service provider determines creation of the requested resource
conflicts with existing resources; e.g., a "User" resource with a conflicts with existing resources; e.g., a "User" resource with a
duplicate "userName", the service provider MUST return an HTTP Status duplicate "userName", the service provider MUST return an HTTP Status
409, with "scimType" error code of "uniqueness" as per Section 3.12. 409, with "scimType" error code of "uniqueness" as per Section 3.12.
Below, in the following example, a client sends a POST request In the following example, a client sends a POST request containing a
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: ...
{ {
"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 13, line 9 skipping to change at page 13, line 9
"familyName":"Jensen", "familyName":"Jensen",
"givenName":"Barbara" "givenName":"Barbara"
}, },
"userName":"bjensen" "userName":"bjensen"
} }
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, "/Users" corresponding resource type for the endpoint. For example, a POST to
will set "resourceType" to "User", and "/Groups" will set the endpoint "/Users" will set "resourceType" to "User", and
"resourceType" to "Group". "/Groups" will set "resourceType" to "Group".
3.4. Retrieving Resources 3.4. Retrieving Resources
Resources are retrieved via opaque, unique URLs or via Query (see Resources MAY be retrieved via opaque, unique URLs or via Query (see
Section 3.4.2). The attributes returned are defined in the server's Section 3.4.2). The attributes returned are defined in the server's
attribute schema (see Section 8.7 [I-D.ietf-scim-core-schema]) and attribute schema (see Section 8.7 [I-D.ietf-scim-core-schema]) and
request parameters (see Section 3.9). By default, resource request parameters (see Section 3.9). By default, resource
attributes returned in a response are those whose schema "returned" attributes returned in a response are those attributes whose
setting is "always" or "default". characteristic "returned" setting is "always" or "default" (see
Section 2.2 of [I-D.ietf-scim-core-schema]).
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}" or "/Groups/{id}", or
"/Schemas/{id}". "/Schemas/{id}", where "{id}" is a resource identifier (for example
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 below example retrieves a single User via the "/Users" endpoint.
GET /Users/2819c223-7f76-453a-919d-413861904646 GET /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
skipping to change at page 14, line 48 skipping to change at page 14, line 48
"type":"work" "type":"work"
} }
] ]
} }
3.4.2. Query Resources 3.4.2. Query Resources
The SCIM protocol defines a standard set of query parameters that can The SCIM protocol defines a standard set of query parameters that can
be used to filter, sort, and paginate to return zero or more be used to filter, sort, and paginate to return zero or more
resources in a query response. Queries MAY be made against a single resources in a query response. Queries MAY be made against a single
resource or a resource type endpoint (e.g., "/Users"). SCIM service resource or a resource type endpoint (e.g., "/Users"), or the service
providers MAY support additional query parameters not specified here provider Base URI. SCIM service providers MAY support additional
and SHOULD ignore any query parameters they do not recognize. query parameters not specified here and SHOULD ignore any query
parameters they do not recognize instead of rejecting the query for
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. This SHALL NOT be equal to the number of query operation. The value may be larger than the number of
elements in the resources attribute of the list response if resources returned such as when returning a single page (see
pagination (Section 3.4.2.4) is requested. REQUIRED. Section 3.4.2.4) of results where multiple pages are available.
REQUIRED.
Resources A multi-valued list of complex objects containing the Resources A multi-valued list of complex objects containing the
requested resources. This MAY be a subset of the full set of requested resources. This MAY be a subset of the full set of
resources if pagination (Section 3.4.2.4) is requested. REQUIRED resources if pagination (Section 3.4.2.4) is requested. REQUIRED
if "totalResults" is non-zero. if "totalResults" is non-zero.
startIndex The 1-based index of the first result in the current set startIndex The 1-based index of the first result in the current set
of list results. REQUIRED when partial results returned due to of list results. REQUIRED when partial results returned due to
pagination. pagination.
itemsPerPage The number of resources returned in a list response itemsPerPage The number of resources returned in a list response
page. REQUIRED when partial results returned due to pagination. page. REQUIRED when partial results returned due to pagination.
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 200) with "totalResults" set to a value of 0.
The query example 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 15, line 46 skipping to change at page 16, line 14
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":[
{ {
"id":"2819c223-7f76-453a-919d-413861904646",
"userName":"bjensen" "userName":"bjensen"
}, },
{ {
"id":"c75ad752-64ae-4823-840d-ffa80929976c",
"userName":"jsmith" "userName":"jsmith"
} }
] ]
} }
Note that in the above example, "id" is returned because the "id"
attribute has the "returned" characteristic of "always".
3.4.2.1. Query Endpoints 3.4.2.1. Query Endpoints
Queries MAY be performed against a SCIM resource object, a resource Queries MAY be performed against a SCIM resource object, a resource
type endpoint, or a SCIM server root. For example: type endpoint, or a SCIM server root. For example:
"/Users/{id}" "/Users/{id}"
"/Users" "/Users"
"/Groups" "/Groups"
A query against a server root indicates that ALL resources within the A query against a server root indicates that all resources within the
server SHALL be included subject to filtering. A filter expression server SHALL be included subject to filtering. A filter expression
using "meta.resourceType" MAY be used to restrict results to one or using "meta.resourceType" MAY be used to restrict results to one or
more specific resource types (to exclude others). For example: more specific resource types (to exclude others). For example:
filter=(meta.resourceType eq User) or (meta.resourceType eq Group) filter=(meta.resourceType eq User) or (meta.resourceType eq Group)
If a SCIM service provider determines that too many results would be If a SCIM service provider determines that too many results would be
returned (e.g., because a client queried a resource type endpoint or returned (e.g., because a client queried a resource type endpoint or
the server base URI), the server SHALL reject the request by the server base URI), the server SHALL reject the request by
returning an HTTP response with "status" 400 and json attribute returning an HTTP response with "status" 400 and json attribute
"scimType" set to "tooMany" (see Table 8). "scimType" set to "tooMany" (see Table 9).
When processing query operations across 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 as FALSE.
3.4.2.2. Filtering 3.4.2.2. Filtering
Filtering is an OPTIONAL parameter for SCIM service providers. Filtering is an OPTIONAL parameter for SCIM service providers.
Clients MAY discover service provider filter capabilities by looking Clients MAY discover service provider filter capabilities by looking
at the "filter" attribute of the "ServiceProviderConfig" (see at the "filter" attribute of the "ServiceProviderConfig" (see
Section 5 and Section 8.5 [I-D.ietf-scim-core-schema]). Clients MAY Section 4). Clients MAY request a subset of resources by specifying
request a subset of resources by specifying the "filter" query the "filter" query parameter containing a filter expression. When
parameter containing a filter expression. When specified only those specified only those resources matching the filter expression SHALL
resources matching the filter expression SHALL be returned. The be returned. The expression language that is used with the filter
expression language that is used in the filter parameter supports parameter supports references to attributes and literals.
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 Boolean The filter parameter MUST contain at least one valid expression (see
expression. Each expression MUST contain an attribute name followed Table 3). Each expression MUST contain an attribute name followed by
by an attribute operator and optional value. Multiple expressions an attribute operator and optional value. Multiple expressions MAY
MAY be combined using the two logical operators. Furthermore be combined using a logical operators (see Table 4). Expressions MAY
expressions can be grouped together using "()". be grouped together using 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 the following
table. 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 |
skipping to change at page 18, line 44 skipping to change at page 19, line 19
| | | string attribute types, this is a | | | | string attribute types, this is a |
| | | lexicographical comparison and for | | | | lexicographical comparison and for |
| | | DateTime types, it is a chronological | | | | DateTime types, it is a chronological |
| | | comparison. For Integer attributes it is | | | | comparison. For Integer attributes it is |
| | | a comparison by numeric value. Boolean | | | | a comparison by numeric value. Boolean |
| | | and Binary attributes SHALL cause a | | | | and Binary attributes SHALL cause a |
| | | failed response (HTTP Status 400) with | | | | failed response (HTTP Status 400) with |
| | | scimType of invalidFilter. | | | | scimType of invalidFilter. |
+----------+-------------+------------------------------------------+ +----------+-------------+------------------------------------------+
Table 2: 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 And | The filter is only a match if both |
| | | expressions evaluate to true. | | | | expressions evaluate to true. |
| or | Logical or | The filter is a match if either | | or | Logical or | The filter is a match if either |
| | | expression evaluates to true. | | | | expression evaluates to true. |
| not | Not | The filter is a match if the expression | | not | Not | The filter is a match if the expression |
| | function | evaluates to false. | | | function | evaluates to false. |
+----------+-------------+------------------------------------------+ +----------+-------------+------------------------------------------+
Table 3: Logical Operators Table 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., evaluate "or" |
| | | logical operators before logical "and" | | | | logical operators before logical "and" |
| | | operators. | | | | operators. |
| [ ] | Complex | Service providers MAY support complex | | [ ] | Complex | Service providers MAY support complex |
skipping to change at page 19, line 38 skipping to change at page 20, line 25
| | filter | applied to the same value of a parent | | | filter | applied to the same value of a parent |
| | grouping | attribute specified immediately before | | | grouping | attribute specified immediately before |
| | | the left square bracket ("["). The | | | | the left square bracket ("["). The |
| | | expression within square brackets ("[" | | | | expression within square brackets ("[" |
| | | and "]") MUST be a valid filter | | | | and "]") MUST be a valid filter |
| | | expression based upon sub-attributes of | | | | expression based upon sub-attributes of |
| | | the parent attribute. Nested expressions | | | | the parent attribute. Nested expressions |
| | | MAY be used. See examples below. | | | | MAY be used. See examples below. |
+----------+-------------+------------------------------------------+ +----------+-------------+------------------------------------------+
Table 4: Grouping Operators Table 5: Grouping Operators
SCIM filters MUST conform to the following ABNF rules as per SCIM filters MUST conform to the following ABNF [RFC5234] rules as
[RFC5234] 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-attribs 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)
skipping to change at page 20, line 41 skipping to change at page 21, line 41
ATTRNAME = ALPHA *(nameChar) ATTRNAME = ALPHA *(nameChar)
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, the "compValue" (comparison value) rule is built In the above ABNF rules, the "compValue" (comparison value) rule is
on JSON Data Interchange format ABNF rules as specified in [RFC7159], built on JSON Data Interchange format ABNF rules as specified in
"DIGIT" and "ALPHA" are defined per Appendix B.1 of [RFC5234] and, [RFC7159], "DIGIT" and "ALPHA" are defined per Appendix B.1 of
"URI" is defined per Appendix A of [RFC3986]. [RFC5234] and, "URI" is defined per Appendix A of [RFC3986].
Filters MUST be evaluated using standard order of operations Filters MUST be evaluated using the following order of operations in
[Order-Operations]. Attribute operators have the highest precedence, order of precedence:
followed by the grouping operator (i.e, parentheses), followed by the
logical AND operator, followed by the logical OR operator. 1. Grouping Operators
2. Logical Operators. Where "not" takes precedence over "and",
which takes precedence over "or".
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 resource MUST match if any of the instances of the attribute, the filter matches if any of the values of the specified
given attribute match the specified criterion; e.g., if a User has attribute match the specified criterion; e.g., if a User has multiple
multiple emails values, only one has to match for the entire User to emails values, only one has to match for the entire User to match.
match. For complex attributes, a fully qualified Sub-Attribute MUST For complex attributes, a fully qualified Sub-Attribute MUST be
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 and to example, to filter by userName the parameter value is "userName". To
filter by first name, the parameter value is name.givenName. filter by first name, the parameter value is "name.givenName".
When applying a comparison (e.g., "eq") or presence filter (e.g.,
"pr"), to a defaulted attribute the service provider SHALL use the
value that was returned to the client that last created or modified
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 an operation is not recognized and return a HTTP 400 error with a scim
appropriate human readable response. For example, if a client error type of "invalidFilter" and an appropriate human readable
specified an unsupported operator named 'regex' the service provider response as per Section 3.12. For example, if a client specified an
should specify an error response description identifying the client unsupported operator named 'regex' the service provider should
error; e.g., 'The operator 'regex' is not supported.' specify an error response description identifying the client error;
e.g., 'The operator 'regex' is not supported.'
String type attributes are case insensitive by default unless the When comparing attributes of type String, the case sensitivity for
attribute type is defined as case exact. Attribute comparison String type attributes SHALL be determined by the attribute's
operators 'eq', 'co', and 'sw' MUST perform caseIgnore matching for "caseExact" characteristic (see Section 2.2
all string attributes unless the attribute is defined as case exact. [I-D.ietf-scim-core-schema]).
By default all string attributes are case insensitive.
Clients MAY query by schema or schema extensions by using a filter Clients MAY query by schema or schema extensions by using a filter
expression including the "schemas" attribute. expression including the "schemas" attribute (as shown in the
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 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"
skipping to change at page 23, line 7 skipping to change at page 24, line 7
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. Sorting allows clients to specify the order in Sort is OPTIONAL. Clients MAY discover sort capability by looking at
which resources are returned by specifying a combination of sortBy the "sort" attribute of the service provider configuration (see
and sortOrder URL parameters. Section 4). Sorting allows clients to specify the order in which
resources are returned by specifying a combination of sortBy and
sortOrder URL parameters.
sortBy The sortBy parameter specifies the attribute whose value sortBy The sortBy parameter specifies the attribute whose value
SHALL be used to order the returned responses. If the sortBy SHALL be used to order the returned responses. If the sortBy
attribute corresponds to a singular attribute, resources are attribute corresponds to a singular attribute, resources are
sorted according to that attribute's value; if it's a multi-valued sorted according to that attribute's value; if it's a multi-valued
attribute, resources are sorted by the value of the primary attribute, resources are sorted by the value of the primary
attribute (see Section 2.4 [I-D.ietf-scim-core-schema]), if any, attribute (see Section 2.4 [I-D.ietf-scim-core-schema]), if any,
or else the first value in the list, if any. If the attribute is or else the first value in the list, if any. If the attribute is
complex the attribute name must be a path to a sub-attribute in complex the attribute name must be a path to a sub-attribute in
standard attribute notation (Section 3.10) ; e.g., standard attribute notation (Section 3.10) ; e.g.,
skipping to change at page 23, line 41 skipping to change at page 24, line 43
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. Pagination is not session based hence clients SHOULD never provider. Because pagination is not stateful, clients MUST be
assume repeatable results. For example, a request for a list of 10 prepared to handle inconsistent results. For example, a request for
resources beginning with a startIndex of 1 MAY return different a list of 10 resources beginning with a startIndex of 1 MAY return
results when repeated as a resource in the original result could be different results when repeated as a resource in the original result
deleted or new ones could be added in-between requests. Pagination could be deleted or new ones could be added in-between requests.
parameters and general behavior are derived from the OpenSearch Pagination parameters and general behavior are derived from the
Protocol [OpenSearch]. OpenSearch Protocol [OpenSearch].
The following table describes the URL pagination parameters. The following table describes the URL pagination parameters.
+------------+----------------------------+-------------------------+ +------------+----------------------------+-------------------------+
| Parameter | Description | Default | | Parameter | Description | Default |
+------------+----------------------------+-------------------------+ +------------+----------------------------+-------------------------+
| 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. | |
skipping to change at page 24, line 24 skipping to change at page 25, line 24
| | 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 SHALL | though MAY return fewer |
| | be interpreted as "0". A | results. If | | | be interpreted as "0". A | results. If |
| | value of "0" indicates no | unspecified, the | | | value of "0" indicates no | unspecified, the |
| | resource results are to be | maximum number of | | | resource results are to be | maximum number of |
| | returned except for | results is set by the | | | returned except for | results is set by the |
| | "totalResults". | service provider. | | | "totalResults". | service provider. |
+------------+----------------------------+-------------------------+ +------------+----------------------------+-------------------------+
Table 5: Pagination Request parameters Table 6: Pagination Request parameters
The following table describes the query response pagination The following table describes the query response pagination
attributes specified by the service provider. attributes specified by the service provider.
+--------------+----------------------------------------------------+ +--------------+----------------------------------------------------+
| Element | Description | | Element | Description |
+--------------+----------------------------------------------------+ +--------------+----------------------------------------------------+
| itemsPerPage | Non-negative Integer. Specifies the number of | | itemsPerPage | Non-negative Integer. Specifies the number of |
| | 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 | | totalResults | Non-negative Integer. Specifies the total number |
| | of results matching the client query; e.g., 1000. | | | 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 6: 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
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
The response to the query above returns metadata regarding paging The response to the query above returns metadata regarding paging
similar to the following example (actual resources removed for similar to the following example (actual resources removed for
brevity): brevity):
skipping to change at page 25, line 47 skipping to change at page 26, line 47
names of resource attributes to be removed from the default set of names of resource attributes to be removed from the default set of
attributes to return. This parameter SHALL have no effect on attributes to return. This parameter SHALL have no effect on
attributes whose schema "returned" setting is "always" see Server attributes whose schema "returned" setting is "always" see Server
Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in
standard attribute notation (Section 3.10) form. See additional standard attribute notation (Section 3.10) form. See additional
retrieval query parameters (Section 3.9). retrieval query parameters (Section 3.9).
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 the HTTP POST verb is intended to be a query
operation. operation.
To create a new query result set, a SCIM client sends an HTTP POST To create a new query result set, a SCIM client sends an HTTP POST
request to the desired SCIM resource endpoint (ending in '/.search'). request to the desired SCIM resource endpoint (ending in "/.search").
The body of the POST request MAY include any of the parameters as The body of the POST request MAY include any of the parameters as
defined in Section 3.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. additional retrieval query parameters (Section 3.9). OPTIONAL.
excludedAttributes A multi-valued list of strings indicating the excludedAttributes A multi-valued list of strings indicating the
names of resource attributes to be removed from the default set of names of resource attributes to be removed from the default set of
skipping to change at page 28, line 18 skipping to change at page 28, line 39
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":[
{ {
"meta":{ "id":"2819c223-7f76-413861904646",
"location":
"https://example.com/Users/2819c223-7f76-413861904646",
"resourceType":"User",
"lastModified": ...
},
"userName":"jsmith", "userName":"jsmith",
"displayName":"Smith, James" "displayName":"Smith, James"
}, },
{ {
"meta":{ "id":"c8596b90-7539-4f20968d1908",
"location":
"https://example.com/Groups/c8596b90-7539-4f20968d1908",
"resourceType":"Group",
"lastModified": ...
},
"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 via PUT or PATCH, Resources can be modified in whole or in part using HTTP "PUT" or
respectively. Implementers MUST support PUT as specified in "PATCH", respectively. Implementers MUST support "PUT" as specified
Section 4.3 [RFC7231]. Resources such as Groups MAY be very large in Section 4.3 [RFC7231]. Resources such as Groups may be very large
hence implementers SHOULD support HTTP PATCH [RFC5789] to enable hence implementers SHOULD support HTTP PATCH [RFC5789] to enable
partial resource modifications. partial resource modifications. Service provider support for HTTP
"PATCH" may be discovered by querying the service provider
configuration (see Section 4).
3.5.1. Replacing with PUT 3.5.1. Replacing with PUT
HTTP PUT is used to perform a full update of a resource's attributes. HTTP PUT is used to replace a resource's attributes. For example,
Clients that MAY have previously retrieved the entire resource in clients that have previously retrieved the entire resource in advance
advance and revised it, MAY replace the resource using an HTTP PUT. and revised it, MAY replace the resource using an HTTP PUT. Because
Because SCIM resource identifiers are typically assigned by the SCIM resource identifiers are assigned by the service provider, HTTP
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 intent is to replace all attributes, SCIM clients
MAY send all attributes regardless of each attribute's mutability. MAY send all attributes regardless of each attribute's mutability.
The server will apply attribute by attribute replace according to the The server will apply attribute by attribute replace according to the
following attribute mutability rules: 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 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 a client has access to, or understands, all of the
resource's attributes when deciding whether non-asserted resource's attributes when deciding whether non-asserted
attributes SHALL be removed or defaulted. Clients that would like attributes SHALL be removed or defaulted. Clients that want to
to override a server defaults, MAY specify "null" for a single- override a server's defaults MAY specify "null" for a single-
valued attribute or an empty array "[]" for a multi-valued valued attribute, or an empty array "[]" for a multi-valued
attribute to clear all values. attribute to clear all values.
immutable If value(s) are already set for the attribute, the input immutable If value(s) are already set for the attribute, the input
value(s) MUST match or HTTP status 400 SHOULD be returned with value(s) MUST match or HTTP status 400 SHOULD be returned with
error code "mutability". If the service provider has no existing "scimType" error code "mutability". If the service provider has
values, the new value(s) SHALL be applied. no existing values, the new value(s) SHALL be applied.
readOnly Any values provided (e.g., meta.resourceType) SHALL be readOnly Any values provided SHALL be ignored.
ignored.
If an attribute is "required", clients MUST specify the attribute in If an attribute is "required", clients MUST specify the attribute in
the PUT request. the PUT request.
Unless otherwise specified a successful PUT operation returns a 200 Unless otherwise specified, a successful PUT operation returns a 200
OK response code and the entire resource within the response body, OK response code and the entire resource within the response body,
enabling the client to correlate the client's and the service enabling the client to correlate the client's and the service
provider's views of the updated resource. Example: provider's views of the updated resource. Example:
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"
skipping to change at page 31, line 44 skipping to change at page 31, line 44
"location": "location":
"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"b431af54f0671a2\"" "version":"W\/\"b431af54f0671a2\""
} }
} }
3.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. The general form operations to "add", "remove", or "replace" values. Clients may
of the SCIM patch request is based on JavaScript Object Notation discover service provider support for PATCH by querying the service
(JSON) Patch [RFC6902]. One difference between SCIM patch and JSON provider configuration (see Section 4).
patch is that SCIM servers do not support array indexing and may not
support all [RFC6902] operation types.
The body of each request MUST contain the following "schemas" The general form of the SCIM patch request is based on JavaScript
attribute with the URI value of: Object Notation (JSON) Patch [RFC6902]. One difference between SCIM
"urn:ietf:params:scim:api:messages:2.0:PatchOp". patch and JSON patch is that SCIM servers do not support array
indexing and do not support [RFC6902] operation types relating to
array element manipulation such as "move".
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 body of an HTTP PATCH request MUST contain the attribute The body of an HTTP PATCH request MUST contain the attribute
"Operations", whose value is an array of one or more patch "Operations", whose value is an array of one or more patch
operations. Each patch operation object MUST have exactly one "op" operations. Each patch operation object MUST have exactly one "op"
member, whose value indicates the operation to perform and MAY be one member, whose value indicates the operation to perform and MAY be one
of "add", "remove", or "replace". The semantics of each operation of "add", "remove", or "replace". The semantics of each operation
are defined in the following sub-sections. are defined in the following sub-sections.
The following is an example representation of a PATCH request showing The following is an example representation of a PATCH request showing
the basic JSON structure (non-normative): the basic JSON structure (non-normative):
skipping to change at page 32, line 40 skipping to change at page 32, line 41
"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
A "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" values 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\"]"
skipping to change at page 33, line 40 skipping to change at page 33, line 40
the attribute had no previous value. An operation that is not the attribute had no previous value. An operation that is not
compatible with an attribute's mutability or schema SHALL return the compatible with an attribute's mutability or schema SHALL return the
appropriate HTTP response status code and a JSON detail error appropriate HTTP response status code and a JSON detail error
response as defined in Section 3.12. response as defined in 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
skipping to change at page 45, line 41 skipping to change at page 45, line 41
], ],
"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 error code for all operations associated with the previously deleted
Id. Service providers MUST also omit the resource from future query resource. Service providers MUST omit the resource from future query
results. In addition the service provider SHOULD NOT consider the results. In addition the service provider SHOULD NOT consider the
deleted resource in conflict calculation. For example if a User deleted resource in conflict calculation. For example if a User
resource is deleted, a CREATE request for a User resource with the resource is deleted, a CREATE request for a User resource with the
same userName as the previously deleted resource SHOULD NOT fail with same userName as the previously deleted resource SHOULD NOT fail with
a 409 error due to userName conflict. a 409 error due to userName conflict.
DELETE /Users/2819c223-7f76-453a-919d-413861904646 DELETE /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"c310cd84f0281b7" If-Match: W/"c310cd84f0281b7"
skipping to change at page 46, line 36 skipping to change at page 46, line 36
"Resource 2819c223-7f76-453a-919d-413861904646 not found", "Resource 2819c223-7f76-453a-919d-413861904646 not found",
"code":"404" "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. The body of a a bulk operation contains a set in a single request. Support for bulk requests can be discovered by
of HTTP resource operations using one of the API supported HTTP querying the service provider configuration (see Section 4). The
methods; i.e., POST, PUT, PATCH or DELETE. body of a a bulk operation contains a set of HTTP resource operations
using one of the API supported HTTP methods; i.e., POST, PUT, PATCH
or DELETE.
Bulk requests are identified using the following URI: Bulk requests are identified using the following schemas 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 common
attributes defined in SCIM core schema. attributes defined in SCIM core schema.
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 core schema.
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: Operations 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 is MAY be used if version The current resource version. Version MAY be used if the
the service provider supports ETags and the method is PUT, service provider supports ETags and the method is PUT, PATCH,
PATCH, or DELETE. 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 the 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 method
values must specify the path to a specific resource; e.g., values must specify the path to a specific resource; e.g.,
/Users/2819c223-7f76-453a-919d-413861904646. REQUIRED in a /Users/2819c223-7f76-453a-919d-413861904646. REQUIRED in a
request. request.
data The resource data as it would appear for a single POST, PUT data The resource data as it would appear for a single POST, PUT
or PATCH resource operation. REQUIRED in a request when method or PATCH resource operation. REQUIRED in a request when method
skipping to change at page 48, line 21 skipping to change at page 48, line 21
returned. returned.
The service provider MUST continue performing as many changes as The service provider MUST continue performing as many changes as
possible and disregard partial failures. The client MAY override possible and disregard partial failures. The client MAY override
this behavior by specifying a value for the "failOnErrors" attribute. this behavior by specifying a value for the "failOnErrors" attribute.
The failOnErrors attribute defines the number of errors that the The failOnErrors attribute defines the number of errors that the
service provider should accept before failing the remaining service provider should accept before failing the remaining
operations returning the response. operations returning the response.
To be able to reference a newly created resource the attribute bulkId To be able to reference a newly created resource the attribute bulkId
MUST be specified when creating new resources. The "bulkId" is MAY be specified when creating new resources. The "bulkId" is
defined by the client as a surrogate identifier in a POST operation defined by the client as a surrogate identifier in a POST operation
(see Section 3.7.2). The service provider MUST return the same (see Section 3.7.2). The service provider MUST return the same
"bulkId" together with the newly created resource. The "bulkId" can "bulkId" together with the newly created resource. The "bulkId" can
then be used by the client to map the service provider id with the then be used by the client to map the service provider id with the
"bulkId" of the created resource. "bulkId" of the created resource.
A SCIM service provider MAY elect to optimize a sequence operations A SCIM service provider MAY elect to optimize a sequence operations
received (e.g., to improve processing performance). When doing so, received (e.g., to improve processing performance). When doing so,
the service provider MUST ensure the clients intent is preserved and the service provider MUST ensure the client's intent is preserved and
the same stateful result is achieved as for non-optimized processing. the same stateful result is achieved as for non-optimized processing.
For example, before a "User" can be added to a "Group", they must For example, before a "User" can be added to a "Group", they must
first be created. Processing these requests out of order, might first be created. Processing these requests out of order, might
result in a failure to add the new "User" to the "Group". result in a failure to add the new "User" to the "Group".
3.7.1. Circular Reference Processing 3.7.1. Circular Reference Processing
The service provider MUST try to resolve circular cross references The service provider MUST try to resolve circular cross references
between resources in a single bulk job but MAY stop after a failed between resources in a single bulk job but MAY stop after a failed
attempt and instead return the status code 409 Conflict. The attempt and instead return the status code 409 Conflict. The
skipping to change at page 61, line 4 skipping to change at page 60, line 36
"method": "DELETE", "method": "DELETE",
"status": "404", "status": "404",
"response":{ "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.", "detail":"Resource does not exist.",
"status":"404" "status":"404"
} }
} }
] ]
} }
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [
{
"location":
"https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST",
"bulkId": "qwerty",
"version": "W\/\"4weymrEsh5O6cAEK\"",
"status": "201"
},
{
"location":
"https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"method": "POST",
"bulkId": "ytrewq",
"version": "W\/\"lha5bbazU3fNvfe5\"",
"status": "201"
}
]
}
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 Section 5 and 8.5 of [I-D.ietf-scim-core-schema]). If
either limits are exceeded the service provider MUST return the HTTP either limits are exceeded the service provider MUST return the HTTP
response code 413 Request Entity Too Large. The returned response response code 413 Request Entity Too Large. The returned response
MUST specify the limit exceeded in the body of the error response. MUST specify the limit exceeded in the body of the error response.
skipping to change at page 62, line 20 skipping to change at page 61, line 32
{ {
"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 respond with JSON structured Servers MUST accept requests and be able to respond with JSON
responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default structured responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be
encoding format. the default encoding format. Other media types MAY be supported by
service 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 HTTP header "Content-Type" as specified in
Section 3.1.1.5 [RFC7231] and MAY specify the desired response data Section 3.1.1.5 [RFC7231] and MAY specify the desired response data
format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g., format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g.,
"Accept: application/scim+json" or via URI suffix; e.g., "Accept: application/scim+json" or via URI suffix; e.g.,
GET /Users/2819c223-7f76-453a-919d-413861904646.scim GET /Users/2819c223-7f76-453a-919d-413861904646.scim
Host: example.com Host: example.com
skipping to change at page 63, line 10 skipping to change at page 62, line 24
Elements with nested elements are represented as objects in JSON; Elements with nested elements are represented as objects in JSON;
e.g, e.g,
"attribute": { "subattribute1": "value1", "subattribute2": "value2" } "attribute": { "subattribute1": "value1", "subattribute2": "value2" }
3.9. Additional Operation Response Parameters 3.9. Additional Operation Response Parameters
For any SCIM operation where a resource representation is returned For any SCIM operation where a resource representation is returned
(e.g., HTTP GET), the attributes returned are defined as the minimum (e.g., HTTP GET), the attributes returned are defined as the minimum
attribute set plus default attributes set. The minimum set are those attribute set plus default attributes set. The minimum set are those
attributes whose schema have "returned" set to "always". The default attributes that have their "returned" characteristic set to "always"
attribute set are those attributes whose schema have "returned" set (see Section 2.2 of [I-D.ietf-scim-core-schema]). The default
to "default". attribute set are those attributes that have the "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 sub-
attributes explicitly requested by the "attributes" attributes explicitly requested by the "attributes"
skipping to change at page 64, line 4 skipping to change at page 63, line 11
notation (Section 3.10) form (e.g., userName, name, emails). notation (Section 3.10) form (e.g., userName, name, emails).
. .
GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Giving the response Giving the response
HTTP/1.1 200 OK HTTP/1.1 200 OK
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",
"userName":"bjensen", "userName":"bjensen"
"meta":{
"resourceType": "User",
"created":"2011-08-01T18:29:49.793Z",
"lastModified":"2011-08-01T18:29:49.793Z",
"location":
"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"a330bc54f0671c9\""
}
} }
3.10. Attribute Notation 3.10. Attribute Notation
All operations share a common scheme for referencing simple and All operations share a common scheme for referencing simple and
complex attributes. In general, attributes are identified by complex attributes. In general, attributes are uniquely identified
prefixing the attribute name with its schema URN separated by a ':' by prefixing the attribute name with its schema URN separated by a
character; e.g., the core User resource attribute 'userName' is colon (":") character; e.g., the core User resource attribute
identified as "urn:ietf:params:scim:schemas:core:2.0:User:userName". 'userName' is identified as
Clients MAY omit core schema attribute URN prefixes though MUST fully "urn:ietf:params:scim:schemas:core:2.0:User:userName". Clients MAY
qualify extended attributes with the associated resource URN; e.g., omit core schema attribute URN prefixes but SHOULD fully qualify
the attribute 'age' defined in extended attributes with the associated schema extension URN to avoid
"urn:ietf:params:scim:schemas:exampleCo:2.0:hr" is fully encoded as naming conflicts. For example, the attribute 'age' defined in
"urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age". Complex "urn:ietf:params:scim:schemas:exampleCo:2.0:hr" is uniquely
attributes' sub-attributes are referenced via nested, dot ('.') identified as "urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age".
notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For Complex attributes' sub-attributes are referenced via nested, dot
example, the fully qualified path for a User's givenName is ('.') notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}.
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 3 ways:
o A service provider that does NOT support this feature SHOULD o A service provider that does NOT support this feature SHOULD
respond with status 403 (FORBIDDEN). respond with status 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 308 to the resource associated with the authenticated
subject. The client MAY then repeat the request at the indicated subject. The client MAY then repeat the request at the indicated
location. 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.
skipping to change at page 65, line 42 skipping to change at page 64, line 42
readable explanations. Error responses are identified using the readable explanations. Error responses are identified using the
following "schema" URI: following "schema" URI:
"urn:ietf:params:scim:api:messages:2.0:Error". The following "urn:ietf:params:scim:api:messages:2.0:Error". The following
attributes are defined for a SCIM error response using a JSON body: attributes are defined for a SCIM error response using a JSON body:
status status
The HTTP status code (see Section 6 [RFC7231]) expressed as a JSON The HTTP status code (see Section 6 [RFC7231]) expressed as a JSON
String. REQUIRED String. REQUIRED
scimType scimType
A SCIM detailed error keyword. See Table 8. OPTIONAL A SCIM detailed 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 |
+--------------+---------------+------------------------------------+ +--------------+---------------+------------------------------------+
skipping to change at page 66, line 51 skipping to change at page 65, line 51
| ENTITY TOO | | 1000,"maxPayload": 1048576} | | ENTITY TOO | | 1000,"maxPayload": 1048576} |
| LARGE | | | | LARGE | | |
| 500 INTERNAL | GET, POST, | An internal error. Implementers | | 500 INTERNAL | GET, POST, | An internal error. Implementers |
| SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive |
| | DELETE | debugging advice | | | DELETE | debugging advice |
| 501 NOT | GET, POST, | Service Provider does not support | | 501 NOT | GET, POST, | Service Provider does not support |
| IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH |
| | DELETE | | | | DELETE | |
+--------------+---------------+------------------------------------+ +--------------+---------------+------------------------------------+
Table 7: 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 400 (Bad Request) responses, the following detail
error types are defined: error types are defined:
+--------------+------------------------------+---------------------+ +--------------+------------------------------+---------------------+
| scimType | Description | Applicability | | scimType | Description | Applicability |
+--------------+------------------------------+---------------------+ +--------------+------------------------------+---------------------+
| invalidFilte | The specified filter syntax | GET(Section 3.4.2), | | invalidFilte | The specified filter syntax | GET(Section 3.4.2), |
| r | was invalid (does not comply | POST (Search - | | r | was invalid (does not comply | POST (Search - |
| | with Figure 1) or the | Section 3.4.3), | | | with Figure 1) or the | Section 3.4.3), |
skipping to change at page 68, line 34 skipping to change at page 67, line 34
| | be completed due to passing | 3.4.2). | | | be completed due to passing | 3.4.2). |
| | of sensitive (e.g., | | | | of sensitive (e.g., | |
| | personal) information in a | | | | personal) information in a | |
| | request URI. For example, | | | | request URI. For example, | |
| | personal information SHALL | | | | personal information SHALL | |
| | NOT be transmitted over | | | | NOT be transmitted over | |
| | request URIs. See Section | | | | request URIs. See Section | |
| | 7.5.2. | | | | 7.5.2. | |
+--------------+------------------------------+---------------------+ +--------------+------------------------------+---------------------+
Table 8: Table of SCIM Detail Error Keyword Values Table 9: Table of SCIM Detail Error Keyword Values
Note that in the table above (Table 8), the applicability table Note that in the table above (Table 9), the applicability table
applies to the normal HTTP method but MAY apply within a SCIM Bulk applies to the normal HTTP method but MAY apply within a SCIM Bulk
operation (via HTTP POST). operation (via HTTP POST).
Error example in response to a non-existent GET request. Error example in response to a non-existent GET request.
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",
skipping to change at page 69, line 14 skipping to change at page 68, line 14
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. API 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 this time of this specification, the
identifier is 'v2'. If specified, the version identifier MUST appear identifier is 'v2'. If specified, the version identifier MUST appear
in the URL path immediately preceding the resource endpoint and in the URL path immediately preceding the resource endpoint and
conform to the following scheme: the character 'v' followed by the conform to the following scheme: the character 'v' followed by the
desired SCIM version number; e.g., a version 'v2' User request is desired SCIM version number; e.g., a version 'v2' User request is
specified as /v2/Users. When specified service providers MUST specified as /v2/Users. When specified service providers MUST
perform the operation using the desired version or reject the perform the operation using the desired version or reject the
request. When omitted service providers SHOULD perform the operation request. When omitted service providers SHOULD perform the operation
using the most recent SCIM protocol version supported by the service using the most recent SCIM protocol version supported by the service
provider. provider.
3.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 [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 clients do not inadvertently overwrite each
others changes, respectively. When supported SCIM ETags MUST be others changes, respectively. When supported, SCIM ETags MUST be
specified as an HTTP header and SHOULD be specified within the specified as an HTTP header and SHOULD be specified within the
'version' attribute contained in the resource's 'meta' attribute. 'version' attribute contained in the resource's 'meta' attribute.
Example: Example 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: ...
{ {
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName":"bjensen", "userName":"bjensen",
skipping to change at page 76, line 7 skipping to change at page 75, line 7
subject to the security considerations of HTTP Section 9 [RFC7230] subject to the security considerations of HTTP Section 9 [RFC7230]
and its related specifications. and its related specifications.
As stated in Section 2.7.1 [RFC7230], a SCIM client MUST NOT generate As stated in Section 2.7.1 [RFC7230], a SCIM client MUST NOT generate
the "userinfo" (i.e., username and password) component (and its "@" the "userinfo" (i.e., username and password) component (and its "@"
delimiter) when an "http" URI reference is generated with a message delimiter) when an "http" URI reference is generated with a message
as they are now disallowed in HTTP. as they are now disallowed in HTTP.
7.2. TLS Support Considerations 7.2. TLS Support Considerations
SCIM resources (e.g., Users and Groups) can contain sensitive SCIM resources (e.g., Users and Groups) contain sensitive information
information including passwords. Therefore, SCIM clients and service including passwords. Therefore, SCIM clients and service providers
providers MUST require the use of a transport-layer security MUST require the use of a transport-layer security mechanism when
mechanism when communicating with SCIM service providers. The SCIM communicating with SCIM service providers. The SCIM service provider
service provider MUST support TLS 1.2 [RFC5246] and MAY support MUST support TLS 1.2 [RFC5246] and MAY support additional transport-
additional transport-layer mechanisms meeting its security layer mechanisms meeting its security requirements. When using TLS,
requirements. When using TLS, the client MUST perform a TLS/SSL the client MUST perform a TLS/SSL server certificate check, per
server certificate check, per [RFC6125]. Implementation security [RFC6125]. Implementation security considerations for TLS can be
considerations for TLS can be found in "Recommendations for Secure found in "Recommendations for Secure Use of TLS and DTLS" [RFC7525].
Use of TLS and DTLS" [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 SHOULD take into account the threats and [RFC6749], implementers MUST take into account threats and
countermeasures documented in Section 8 of countermeasures documented in Section 8 of
[I-D.ietf-oauth-assertions]. [I-D.ietf-oauth-assertions].
7.4. Bearer and Cookie Considerations 7.4. Bearer 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, tokens and
cookies MUST contain sufficient entropy to prevent a random guessing cookies MUST contain sufficient entropy to prevent a random guessing
attack, such as described in Section 5.2 of [RFC6750] and attack, such as described in Section 5.2 of [RFC6750] and
Section 5.1.4.2.2 of [RFC6819]. Section 5.1.4.2.2 of [RFC6819].
When using a bearer token that represents an authorization,
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 OAuth2, 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
skipping to change at page 78, line 23 skipping to change at page 77, line 13
} }
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 counter-measures MAY be used:
o Try to authenticate web UI components that formulate the SCIM o Try to authenticate web UI components that formulate the SCIM
creation request. While the end-user MAY be anonymous, the web creation request. While the end-user may be anonymous, the web
user interface component often has its own way to authenticate to user interface component often has its own way to authenticate to
the SCIM service provider (e.g., has an OAuth client credential the SCIM service provider (e.g., has an OAuth client credential
[RFC6749]) and the web user interface component may implement its [RFC6749]) and the web user interface component may implement its
own measures (e.g., such as CAPTCHA) to ensure a legitimate own measures (e.g., such as CAPTCHA) to ensure a legitimate
request is being made. request is being made.
o Limit the number of requests any particular client MAY make in a o Limit the number of requests any particular client MAY make in a
period of time. period of time.
o For User resources, default newly created resource with an o For User resources, default newly created resource with an
skipping to change at page 81, line 35 skipping to change at page 80, line 24
| 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 9: 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] [I-D.ietf-precis-saslprepbis]
Saint-Andre, P. and A. Melnikov, "Preparation, Saint-Andre, P. and A. Melnikov, "Preparation,
Enforcement, and Comparison of Internationalized Strings Enforcement, and Comparison of Internationalized Strings
Representing Usernames and Passwords", draft-ietf-precis- Representing Usernames and Passwords", draft-ietf-precis-
saslprepbis-16 (work in progress), April 2015. saslprepbis-16 (work in progress), April 2015.
[I-D.ietf-scim-core-schema] [I-D.ietf-scim-core-schema]
Hunt, P., Grizzle, K., Wahlstroem, E., and C. Mortimore, Hunt, P., Grizzle, K., Wahlstroem, E., and C. Mortimore,
"System for Cross-Domain Identity Management: Core "System for Cross-Domain Identity Management: Core
Schema", draft-ietf-scim-core-schema-18 (work in Schema", draft-ietf-scim-core-schema-20 (work in
progress), April 2015. 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, March 1997.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, November 2003.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005. 3986, January 2005.
skipping to change at page 82, line 30 skipping to change at page 81, line 20
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC
5789, March 2010. 5789, March 2010.
[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, March 2011.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
6749, October 2012.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, October 2012.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, March 2014.
[RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Message Syntax and Routing", RFC 7230, June (HTTP/1.1): Message Syntax and Routing", RFC 7230, June
2014. 2014.
[RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Semantics and Content", RFC 7231, June 2014. (HTTP/1.1): Semantics and Content", RFC 7231, June 2014.
skipping to change at page 83, line 34 skipping to change at page 82, line 34
[I-D.ietf-precis-framework] [I-D.ietf-precis-framework]
Saint-Andre, P. and M. Blanchet, "PRECIS Framework: Saint-Andre, P. and M. Blanchet, "PRECIS Framework:
Preparation, Enforcement, and Comparison of Preparation, Enforcement, and Comparison of
Internationalized Strings in Application Protocols", Internationalized Strings in Application Protocols",
draft-ietf-precis-framework-23 (work in progress), draft-ietf-precis-framework-23 (work in progress),
February 2015. February 2015.
[OpenSearch] [OpenSearch]
Clinton, D., "OpenSearch Protocol 1.1, Draft 5", Dec 2005. Clinton, D., "OpenSearch Protocol 1.1, Draft 5", Dec 2005.
[Order-Operations]
Wikipedia, "Order of Operations: Programming Languages",
Apr 2015.
[RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
April 2011. April 2011.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
6749, October 2012.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, October 2012.
[RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819, Threat Model and Security Considerations", RFC 6819,
January 2013. January 2013.
[RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation
(JSON) Patch", RFC 6902, April 2013. (JSON) Patch", RFC 6902, April 2013.
[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, March 2015.
skipping to change at page 89, line 4 skipping to change at page 87, line 42
Draft 18 - PH - Edits based on IESG feedback Draft 18 - PH - Edits based on IESG feedback
Clarified use of authentication schemes Clarified use of authentication schemes
Nits and wording clarifications Nits and wording clarifications
Corrected definitions of HTTP Status 401/403 Corrected definitions of HTTP Status 401/403
Manager corrected in PATCH example operation (consistent with Manager corrected in PATCH example operation (consistent with
schema and examples) schema and examples)
Removed editor's note regarding Service Provider unique error Removed editor's note regarding Service Provider unique error
codes codes
Updated references to SCIM Core Schema and other documents. Updated references to SCIM Core Schema and other documents.
Made capitalization of 'client' and 'service provider' terms Made capitalization of 'client' and 'service provider' terms
consistent (lower case) consistent (lower case)
Add references to draft-ietf-oauth-assertions-18 and draft-ietf- Add references to draft-ietf-oauth-assertions-18 and draft-ietf-
httpauth-basicauth-update-07 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
403
Removed reference to wikipedia and order of operations
General edits to clarify awkward text and typos
Authors' Addresses Authors' Addresses
Phil Hunt (editor) Phil Hunt (editor)
Oracle Corporation Oracle Corporation
Email: phil.hunt@yahoo.com Email: phil.hunt@yahoo.com
Kelly Grizzle Kelly Grizzle
SailPoint SailPoint
 End of changes. 118 change blocks. 
361 lines changed or deleted 372 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/