draft-ietf-scim-api-08.txt   draft-ietf-scim-api-09.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: February 2, 2015 SailPoint Expires: February 13, 2015 SailPoint
M. Ansari M. Ansari
Cisco Cisco
E. Wahlstroem E. Wahlstroem
Nexus Technology Nexus Technology
C. Mortimore C. Mortimore
Salesforce Salesforce
August 1, 2014 August 12, 2014
System for Cross-Domain Identity Management:Protocol System for Cross-Domain Identity Management:Protocol
draft-ietf-scim-api-08 draft-ietf-scim-api-09
Abstract Abstract
The System for Cross-Domain Identity Management (SCIM) specification The System for Cross-Domain Identity Management (SCIM) specification
is designed to make managing user identity in multi-domain based is designed to make managing user identity in multi-domain based
applications and services easier using HTTP Protocol. Examples applications and services easier using HTTP Protocol. Examples
include but are not limited to enterprise to cloud service providers, include but are not limited to enterprise to cloud service providers,
and inter-cloud based scenarios. The specification suite seeks to and inter-cloud based scenarios. The specification suite seeks to
build upon experience with existing schemas and deployments, placing build upon experience with existing schemas and deployments, placing
specific emphasis on simplicity of development and integration, while specific emphasis on simplicity of development and integration, while
skipping to change at page 1, line 49 skipping to change at page 1, line 49
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 February 2, 2015. This Internet-Draft will expire on February 13, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 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 37 skipping to change at page 2, line 37
3. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 4 3. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 6 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 6
3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 8 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 8
3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 8 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 8
3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8
3.2.2. Query Resources . . . . . . . . . . . . . . . . . . . 9 3.2.2. Query Resources . . . . . . . . . . . . . . . . . . . 9
3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 20 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 20
3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 23 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 23
3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 24 3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 24
3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 26 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 26
3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 36 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 39
3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 36 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 40
3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 51 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 55
3.7. Additional Operation Response Parameters . . . . . . . . 52 3.7. Additional Operation Response Parameters . . . . . . . . 56
3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 53 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 57
3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 54 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 58
3.10. HTTP Status and Error Response Handling . . . . . . . . . 54 3.10. HTTP Status and Error Response Handling . . . . . . . . . 58
3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 58 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 62
3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 58 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 62
4. Preparation and Comparison of Internationalized Strings . . . 60 4. Preparation and Comparison of Internationalized Strings . . . 64
5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 60 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 64
5.1. Associating Clients to Tenants . . . . . . . . . . . . . 61 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 65
5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 62 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 66
6. Security Considerations . . . . . . . . . . . . . . . . . . . 62 6. Security Considerations . . . . . . . . . . . . . . . . . . . 66
6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 62 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 66
6.2. Disclosure of Sensitive Information in URIs . . . . . . . 62 6.2. Disclosure of Sensitive Information in URIs . . . . . . . 66
6.3. HTTP Considerations . . . . . . . . . . . . . . . . . . . 63 6.3. HTTP Considerations . . . . . . . . . . . . . . . . . . . 67
6.4. Secure Storage and Handling of Sensitive Data . . . . . . 63 6.4. Secure Storage and Handling of Sensitive Data . . . . . . 67
6.5. Case Insensitive Comparision & International Languages . 64 6.5. Case Insensitive Comparision & International Languages . 68
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 64 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 68
7.1. Media Type Registration . . . . . . . . . . . . . . . . . 64 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 68
7.2. SCIM API Message Schema Registry . . . . . . . . . . . . 65 7.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 69
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 66 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 70
8.1. Normative References . . . . . . . . . . . . . . . . . . 66 8.1. Normative References . . . . . . . . . . . . . . . . . . 70
8.2. Informative References . . . . . . . . . . . . . . . . . 67 8.2. Informative References . . . . . . . . . . . . . . . . . 71
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 68 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 72
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 68 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 72
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 68 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 72
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 75
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 7, line 13 skipping to change at page 7, line 13
containing a "User" to the "/Users" endpoint. containing a "User" to the "/Users" endpoint.
POST /Users HTTP/1.1 POST /Users HTTP/1.1
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
{ {
"schemas":["urn:scim:schemas:core:2.0:User"], "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName":"bjensen", "userName":"bjensen",
"externalId":"bjensen", "externalId":"bjensen",
"name":{ "name":{
"formatted":"Ms. Barbara J Jensen III", "formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen", "familyName":"Jensen",
"givenName":"Barbara" "givenName":"Barbara"
} }
} }
In response to the example request above, the server signals a In response to the example request above, the server signals a
successful creation with an HTTP status code 201 (Created) and successful creation with an HTTP status code 201 (Created) and
returns a representation of the resource created. returns a representation of the resource created.
HTTP/1.1 201 Created HTTP/1.1 201 Created
Content-Type: application/scim+json Content-Type: application/scim+json
Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1" ETag: W/"e180ee84f0671b1"
{ {
"schemas":["urn: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",
"externalId":"bjensen", "externalId":"bjensen",
"meta":{ "meta":{
"resourceType":"User", "resourceType":"User",
"created":"2011-08-01T21:32:44.882Z", "created":"2011-08-01T21:32:44.882Z",
"lastModified":"2011-08-01T21:32:44.882Z", "lastModified":"2011-08-01T21:32:44.882Z",
"location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"e180ee84f0671b1\"" "version":"W\/\"e180ee84f0671b1\""
}, },
"name":{ "name":{
skipping to change at page 9, line 11 skipping to change at page 9, line 11
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
The server responds with: The server responds with:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"f250dd84f0671c3" ETag: W/"f250dd84f0671c3"
{ {
"schemas":["urn: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",
"externalId":"bjensen", "externalId":"bjensen",
"meta":{ "meta":{
"resourceType":"User", "resourceType":"User",
"created":"2011-08-01T18:29:49.793Z", "created":"2011-08-01T18:29:49.793Z",
"lastModified":"2011-08-01T18:29:49.793Z", "lastModified":"2011-08-01T18:29:49.793Z",
"location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"f250dd84f0671c3\"" "version":"W\/\"f250dd84f0671c3\""
}, },
"name":{ "name":{
skipping to change at page 9, line 51 skipping to change at page 9, line 51
3.2.2. Query Resources 3.2.2. Query Resources
The SCIM protocol defines a standard set of query parameters that can The SCIM protocol defines a standard set of query parameters that can
be used to filter, sort, and paginate to return zero or more be used to filter, sort, and paginate to return zero or more
resources in a query response. Queries MAY be made against a single resources in a query response. Queries MAY be made against a single
resource or a resource type endpoint (e.g. "/Users"). SCIM service resource or a resource type endpoint (e.g. "/Users"). SCIM service
providers MAY support additional query parameters not specified here providers MAY support additional query parameters not specified here
and SHOULD ignore any query parameters they do not recognize. and SHOULD ignore any query parameters they do not recognize.
Responses MUST be identified using the following URI: Responses MUST be identified using the following URI:
"urn:scim:api:messages:2.0:ListResponse". The following attributes "urn:ietf:params:scim:api:messages:2.0:ListResponse". The following
are defined for responses: attributes are defined for responses:
totalResults The total number of results returned by the list or totalResults The total number of results returned by the list or
query operation. This may not be equal to the number of elements query operation. This may not be equal to the number of elements
in the resources attribute of the list response if pagination in the resources attribute of the list response if pagination
(Section 3.2.2.4) is requested. REQUIRED. (Section 3.2.2.4) is requested. REQUIRED.
Resources A multi-valued list of complex objects containing the Resources A multi-valued list of complex objects containing the
requested resources. This may be a subset of the full set of requested resources. This may be a subset of the full set of
resources if pagination (Section 3.2.2.4) is requested. REQUIRED resources if pagination (Section 3.2.2.4) is requested. REQUIRED
if "totalResults" is non-zero. if "totalResults" is non-zero.
skipping to change at page 10, line 38 skipping to change at page 10, line 38
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:scim:api:messages:2.0:ListResponse"], "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults":2, "totalResults":2,
"Resources":[ "Resources":[
{ {
"userName":"bjensen" "userName":"bjensen"
}, },
{ {
"userName":"jsmith" "userName":"jsmith"
} }
] ]
} }
skipping to change at page 17, line 9 skipping to change at page 17, line 9
all string attributes unless the attribute is defined as case exact. all string attributes unless the attribute is defined as case exact.
By default all string attributes are case insensitive. By default all string attributes are case insensitive.
Clients MAY query by schema or schema extensions by using a filter Clients MAY query by schema or schema extensions by using a filter
expression including the "schemas" attribute. expression including the "schemas" attribute.
The following are examples of valid filters. Some attributes (e.g. The following are examples of valid filters. Some attributes (e.g.
rooms and rooms.number) are hypothetical extensions and are not part rooms and rooms.number) are hypothetical extensions and are not part
of SCIM core schema: of SCIM core schema:
filter=userName eq "bjensen" filter=userName eq "bjensen"
filter=name.familyName co "O'Malley" filter=name.familyName co "O'Malley"
filter=userName sw "J" filter=userName sw "J"
filter=title pr filter=title pr
filter=meta.lastModified gt "2011-05-13T04:42:34Z" filter=meta.lastModified gt "2011-05-13T04:42:34Z"
filter=meta.lastModified ge "2011-05-13T04:42:34Z" filter=meta.lastModified ge "2011-05-13T04:42:34Z"
filter=meta.lastModified lt "2011-05-13T04:42:34Z" filter=meta.lastModified lt "2011-05-13T04:42:34Z"
filter=meta.lastModified le "2011-05-13T04:42:34Z" filter=meta.lastModified le "2011-05-13T04:42:34Z"
filter=title pr and userType eq "Employee" filter=title pr and userType eq "Employee"
filter=title pr or userType eq "Intern" filter=title pr or userType eq "Intern"
filter=schemas eq "urn:scim:schemas:extension:enterprise:2.0:User" filter=schemas eq "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
filter=userType eq "Employee" and (emails co "example.com" or emails filter=userType eq "Employee" and (emails co "example.com" or emails
co "example.org") co "example.org")
filter=userType ne "Employee" and not (emails co "example.com" or filter=userType ne "Employee" and not (emails co "example.com" or
emails co "example.org") emails co "example.org")
filter=userType eq "Employee" and (emails.type eq "work") filter=userType eq "Employee" and (emails.type eq "work")
filter=userType eq "Employee" and emails[type eq "work" and filter=userType eq "Employee" and emails[type eq "work" and
value co "@example.com"] value co "@example.com"]
filter=emails[type eq "work" and value co "@example.com"] or filter=emails[type eq "work" and value co "@example.com"] or
ims[type eq "xmpp" and value co "@foo.com"] ims[type eq "xmpp" and value co "@foo.com"]
filter=addresses[state eq "CA" and rooms[type eq "bedroom" and filter=addresses[state eq "CA" and rooms[type eq "bedroom" and
number gt 2]] number gt 2]]
Figure 2: Example Filters Figure 2: Example Filters
3.2.2.3. Sorting 3.2.2.3. Sorting
Sort is OPTIONAL. Sorting allows clients to specify the order in Sort is OPTIONAL. Sorting allows clients to specify the order in
which resources are returned by specifying a combination of sortBy which resources are returned by specifying a combination of sortBy
and sortOrder URL parameters. and sortOrder URL parameters.
sortBy: The sortBy parameter specifies the attribute whose value sortBy: The sortBy parameter specifies the attribute whose value
skipping to change at page 20, line 12 skipping to change at page 20, line 12
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):
{ {
"totalResults":100, "totalResults":100,
"itemsPerPage":10, "itemsPerPage":10,
"startIndex":1, "startIndex":1,
"schemas":["urn:scim:api:messages:2.0"], "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"Resources":[{ "Resources":[{
... ...
}] }]
} }
Given the example above, to continue paging set the startIndex to 11 Given the example above, to continue paging set the startIndex to 11
and re-fetch; i.e., /Users?startIndex=11&count=10 and re-fetch; i.e., /Users?startIndex=11&count=10
3.2.2.5. Attributes 3.2.2.5. Attributes
skipping to change at page 21, line 9 skipping to change at page 21, line 9
be used to indicate the HTTP POST verb is intended to be a query be used to indicate the HTTP POST verb is intended to be a query
operation. operation.
To create a new query result set, a SCIM client sends an HTTP POST To create a new query result set, a SCIM client sends an HTTP POST
request to the desired SCIM resource endpoint (ending in '/.search'). request to the desired SCIM resource endpoint (ending in '/.search').
The body of the POST request MAY include any of the parameters as The body of the POST request MAY include any of the parameters as
defined in Section 3.2.2. defined in Section 3.2.2.
Query requests MUST be identified using the following URI: Query requests MUST be identified using the following URI:
'urn:scim:api:messages:2.0:SearchRequest'. The following attributes 'urn:ietf:params:scim:api:messages:2.0:SearchRequest'. The following
are defined for query requests: attributes are defined for query requests:
attributes A multi-valued list of strings indicating the names of attributes A multi-valued list of strings indicating the names of
resource attributes to return in the response overriding the set resource attributes to return in the response overriding the set
of attributes that would be returned by default. Attribute names of attributes that would be returned by default. Attribute names
MUST be in standard attribute notation (Section 3.8) form. See MUST be in standard attribute notation (Section 3.8) form. See
additional retrieval query parameters (Section 3.7). OPTIONAL. additional retrieval query parameters (Section 3.7). OPTIONAL.
excludedAttributes A multi-valued list of strings indicating the excludedAttributes A multi-valued list of strings indicating the
names of resource attributes to be removed from the default set of names of resource attributes to be removed from the default set of
attributes to return. This parameter SHALL have no effect on attributes to return. This parameter SHALL have no effect on
skipping to change at page 22, line 16 skipping to change at page 22, line 16
parameters attributes, filter, and count included: parameters attributes, filter, and count included:
POST /.search POST /.search
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
{ {
"schemas": ["urn:scim:api:messages:2.0:SearchRequest"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
"attributes": ["displayName", "userName"], "attributes": ["displayName", "userName"],
"filter": "(displayName sw \"smith\") and (meta.resourceType eq \"User\")", "filter": "(displayName sw \"smith\") and (meta.resourceType eq \"User\")",
"startIndex": 1, "startIndex": 1,
"count": 10 "count": 10
} }
Figure 3: Example POST Query Request Figure 3: Example POST Query Request
A query response is shown with the first page of results. For A query response is shown with the first page of results. For
brevity reasons, only two matches are shown: one User and one Group. brevity reasons, only two matches are shown: one User and one Group.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
Location: https://example.com/.search Location: https://example.com/.search
{ {
"schemas": ["urn: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":{ "meta":{
"location": "location":
"https://example.com/Users/2819c223-7f76-413861904646", "https://example.com/Users/2819c223-7f76-413861904646",
"resourceType":"User", "resourceType":"User",
"lastModified": ... "lastModified": ...
}, },
"userName":"jsmith", "userName":"jsmith",
"displayName":"Smith, James" "displayName":"Smith, James"
}, },
{ {
"meta":{ "meta":{
"location": "location":
"https://example.com/Groups/c8596b90-7539-4f20968d1908", "https://example.com/Groups/c8596b90-7539-4f20968d1908",
"resourceType":"Group", "resourceType":"Group",
"lastModified": ... "lastModified": ...
}, },
"displayName":"Smith Family" "displayName":"Smith Family"
}, },
... ...
] ]
} }
Figure 4: Example POST Query Response Figure 4: Example POST Query Response
3.3. Modifying Resources 3.3. Modifying Resources
Resources can be modified in whole or in part via PUT or PATCH, Resources can be modified in whole or in part via PUT or PATCH,
respectively. Implementers MUST support PUT as specified in respectively. Implementers MUST support PUT as specified in
Section 4.3 [RFC7231]. Resources such as Groups may be very large Section 4.3 [RFC7231]. Resources such as Groups may be very large
hence implementers SHOULD support HTTP PATCH [RFC5789] to enable hence implementers SHOULD support HTTP PATCH [RFC5789] to enable
partial resource modifications. partial resource modifications.
skipping to change at page 25, line 13 skipping to change at page 25, line 13
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"
{ {
"schemas":["urn:scim:api:messages:2.0:User"], "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646", "id":"2819c223-7f76-453a-919d-413861904646",
"userName":"bjensen", "userName":"bjensen",
"externalId":"bjensen", "externalId":"bjensen",
"name":{ "name":{
"formatted":"Ms. Barbara J Jensen III", "formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen", "familyName":"Jensen",
"givenName":"Barbara", "givenName":"Barbara",
"middleName":"Jane" "middleName":"Jane"
}, },
"roles":[], "roles":[],
skipping to change at page 26, line 11 skipping to change at page 26, line 11
} }
] ]
} }
The service responds with the entire, updated User: The service responds with the entire, updated User:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
ETag: W/"b431af54f0671a2" ETag: W/"b431af54f0671a2"
Location:"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646" Location:"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646"
{ {
"schemas":["urn:scim:api:messages:2.0:User"], "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646", "id":"2819c223-7f76-453a-919d-413861904646",
"userName":"bjensen", "userName":"bjensen",
"externalId":"bjensen", "externalId":"bjensen",
"name":{ "name":{
"formatted":"Ms. Barbara J Jensen III", "formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen", "familyName":"Jensen",
"givenName":"Barbara", "givenName":"Barbara",
"middleName":"Jane" "middleName":"Jane"
}, },
"emails":[ "emails":[
skipping to change at page 27, line 7 skipping to change at page 27, line 7
(JSON) Patch [RFC6902]. One difference between SCIM patch and JSON (JSON) Patch [RFC6902]. One difference between SCIM patch and JSON
patch is that SCIM servers do not support array indexing and may not patch is that SCIM servers do not support array indexing and may not
support all [RFC6902] operation types. support all [RFC6902] operation types.
The body of an HTTP PATCH request MUST contain one or more patch The body of an HTTP PATCH request MUST contain one or more patch
operation objects. A patch operation object MUST have exactly one operation objects. A patch operation object MUST have exactly one
"op" member, whose value indicates the operation to perform and MAY "op" member, whose value indicates the operation to perform and MAY
be one of "add", "remove", or "replace". The semantics of each be one of "add", "remove", or "replace". The semantics of each
operation are defined below. operation are defined below.
Each operation object MUST contain the following "schemas" URI: The body of each request MUST contain the following "schemas" URI:
"urn:scim:api:messages:2.0:PatchOp" "urn:ietf:params:scim:api:messages:2.0:PatchOp", followed by an array
of one or more operations. For example:
Operation objects MUST have exactly one "path" member which is a { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"String" containing an attribute path as specified by the following [
ABNF syntax rule: {
"op":"add",
"path":"members",
"value":[
{
"display": "Babs Jensen",
"$ref": "https://example.com/v2/Users/2819c223...413861904646",
"value": "2819c223-7f76-453a-919d-413861904646"
}
]
},
... + additional operations if needed ...
]
}
Example JSON body for SCIM PATCH Request
A "path" attribute value is a String containing an attribute path
describing the target of the operation. The "path" attribute is
OPTIONAL for "add" and "replace" and is REQUIRED for "remove"
operations. See relevant operation sections below for details.
The "path" attribute is described by the following ABNF syntax rule:
PATH = attrPath / valuePath [subAttr] PATH = attrPath / valuePath [subAttr]
Figure 5: SCIM Patch PATH Rule Figure 5: SCIM Patch PATH Rule
The ABNF rules, "attrPath", "valuePath", and "subAttr" are defined in The ABNF rules, "attrPath", "valuePath", and "subAttr" are defined in
Section 3.2.2.2. The "valuePath" rule allows specific values of a Section 3.2.2.2. The "valuePath" rule allows specific values of a
complex, multi-valued attribute to be selected. complex, multi-valued attribute to be selected.
Valid examples of "path" values are as follows: Valid examples of "path" values are as follows:
skipping to change at page 27, line 50 skipping to change at page 28, line 33
Section of [I-D.ietf-scim-core-schema]. For example, a client MAY Section of [I-D.ietf-scim-core-schema]. For example, a client MAY
NOT modify an attribute that has mutability "readOnly" or NOT modify an attribute that has mutability "readOnly" or
"immutable". However, a client MAY "add" a value to an "immutable" "immutable". However, a client MAY "add" a value to an "immutable"
attribute if the attribute had no previous value. An operation that attribute if the attribute had no previous value. An operation that
is not compatibile with an attribute's mutability or schema SHALL is not compatibile with an attribute's mutability or schema SHALL
return the appropriate HTTP response status code and a JSON detail return the appropriate HTTP response status code and a JSON detail
error response as defined in Section 3.10. error response as defined in Section 3.10.
The attribute notation rules described in Section 3.8 apply for The attribute notation rules described in Section 3.8 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 service provider's representation of the "schemas" attribute on the SCIM service provider's representation of
resource SHALL be assumed by default. If one of the PATCH operations the resource SHALL be assumed by default. If one of the PATCH
modifies the "schemas" attribute, subsequent operations SHALL assume operations modifies the "schemas" attribute, subsequent operations
the modified state of the "schemas" attribute. Clients MAY SHALL assume the modified state of the "schemas" attribute. Clients
implicitly modify the "schemas" attribute by adding (or replacing) an MAY implicitly modify the "schemas" attribute by adding (or
attribute with its fully qualified name including schema URN. For replacing) an attribute with its fully qualified name including
example, adding the attribute schema URN. For example, adding the attribute "urn:ietf:params:scim:
"urn:scim:schemas:extension:enterprise:2.0:User:employeeNumber", schemas:extension:enterprise:2.0:User:employeeNumber", automatically
automatically adds the value adds the value
"urn:scim:schemas:extension:enterprise:2.0:User" to the resource's "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" to the
"schemas" attribute. resource's "schemas" attribute.
Each patch operation represents a single action to be applied to the Each patch operation represents a single action to be applied to the
same SCIM resource specified by the request URI. Operations are same SCIM resource specified by the request URI. Operations are
applied sequentially in the order they appear in the array. Each applied sequentially in the order they appear in the array. Each
operation in the sequence is applied to the target resource; the operation in the sequence is applied to the target resource; the
resulting resource becomes the target of the next operation. resulting resource becomes the target of the next operation.
Evaluation continues until all operations are successfully applied or Evaluation continues until all operations are successfully applied or
until an error condition is encountered. until an error condition is encountered.
For a multi-valued attributes, a patch operation that sets a value's For a multi-valued attributes, a patch operation that sets a value's
skipping to change at page 29, line 8 skipping to change at page 29, line 39
existing resource. existing resource.
The operation MUST contain a "value" member whose content specifies The operation MUST contain a "value" member whose content specifies
the value to be added. The value MAY be a quoted value OR it may be the value to be added. The value MAY be a quoted value OR it may be
a JSON object containing the sub-attributes of the complex attribute a JSON object containing the sub-attributes of the complex attribute
specified in the operation's "path". specified in the operation's "path".
The result of the add operation depends upon what the target location The result of the add operation depends upon what the target location
indicated by "path" references: indicated by "path" references:
o If omitted, the target location is assumed to be the resource
itself. The "value" parameter contains a set of attributes to be
added to the resource.
o If the target location does not exist, the attribute and value is o If the target location does not exist, the attribute and value is
added. added.
o If the target location specifies a complex attribute, a set of
sub-attributes SHALL be specified in the "value" parameter.
o If the target location specifies a multi-valued attribute, a new o If the target location specifies a multi-valued attribute, a new
value is added to the attribute. value is added to the attribute.
o if the target location specifies a single-valued attribute, the o if the target location specifies a single-valued attribute, the
existing value is replaced. existing value is replaced.
o If the target location specifies an attribute that does not exist o If the target location specifies an attribute that does not exist
(has no value), the attribute is added with the new value. (has no value), the attribute is added with the new value.
o If the target location exists, the value is replaced. o If the target location exists, the value is replaced.
o If the target location already contains the value specified, no o If the target location already contains the value specified, no
changes SHOULD be made to the resource and a success response changes SHOULD be made to the resource and a success response
SHOULD be returned. Unless other operations change the resource, SHOULD be returned. Unless other operations change the resource,
this operation SHALL NOT change the modify timestamp of the this operation SHALL NOT change the modify timestamp of the
resource. resource.
The following example shows how to add a member to a group. Some The following example shows how to add a member to a group. Some
text removed for readability ("..."): text removed for readability ("..."):
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
{ [
"schemas": ["urn:scim:api:messages:2.0:PatchOp"], {
"op":"add", "op":"add",
"path":"members", "path":"members",
"value":[ "value":[
{ {
"display": "Babs Jensen", "display": "Babs Jensen",
"$ref": "https://example.com/v2/Users/2819c223...413861904646", "$ref": "https://example.com/v2/Users/2819c223...413861904646",
"value": "2819c223-7f76-453a-919d-413861904646" "value": "2819c223-7f76-453a-919d-413861904646"
} }
] ]
} }
]
}
The "display" Sub-Attribute in this request is optional since the If the user was already a member of this group, no changes should be
value attribute uniquely identifies the user to be added. If the made to the resource and a success response should be returned. The
user was already a member of this group, no changes should be made to server responds with either the entire updated Group or no response
the resource and a success response should be returned. The server body:
responds with either the entire updated Group or no response body:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
ETag: W/"b431af54f0671a2" ETag: W/"b431af54f0671a2"
Location: "https://example.com/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" Location: "https://example.com/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce"
The following example shows how to add one or more attributes to a
User resource without using a "path" attribute.
PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
[{
"op":"add",
"value":"{
"emails":[
{
"value":"babs@jensen.org",
"type":"home"
}
],
"nickname":"Babs"
}]
}
In the above example, an additional value is added to the multi-
valued attribute "emails". The second attribute, "nickname" is added
to the User resource. If the resource already had an existing
"nickname", the value is replaced per the processing rules above for
single-valued attributes.
3.3.2.2. Remove Operation 3.3.2.2. Remove Operation
The "remove" operation removes the value at the target location The "remove" operation removes the value at the target location
specified by the "path". The operation performs the following specified by the required attribute "path". The operation performs
functions depending on the target location specified by "path" : the following functions depending on the target location specified by
"path" :
o If "path" is unspecified, the operation fails with HTTP status
"400" and "scimType" of "noTarget".
o If the target location is a single-value attribute, the attribute o If the target location is a single-value attribute, the attribute
and its associated value is removed and the attribute SHALL be and its associated value is removed and the attribute SHALL be
considered unassigned. considered unassigned.
o If the target location is a multi-valued attribute and no filter o If the target location is a multi-valued attribute and no filter
is specified, the attribute and all values are removed and the is specified, the attribute and all values are removed and the
attribute SHALL be considered unassigned. attribute SHALL be considered unassigned.
o If the target location is a multi-valued attribute and a complex o If the target location is a multi-valued attribute and a complex
skipping to change at page 31, line 16 skipping to change at page 32, line 42
readability ("..."): readability ("..."):
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:api:messages:2.0:PatchOp"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"op":"remove", [{
"path":"members[value eq \"2819c223-7f76-...413861904646\"]" "op":"remove",
"path":"members[value eq \"2819c223-7f76-...413861904646\"]"
}]
} }
Remove all members of a group: Remove all members of a group:
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ "schemas": ["urn:scim:api:messages:2.0:PatchOp"], { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"op":"remove","path":"members"} [{
"op":"remove","path":"members"
}]
}
Removal of a value from a complex-multi-valued attribute (request Removal of a value from a complex-multi-valued attribute (request
headers removed for brevity): headers removed for brevity):
{ {
"schemas": ["urn:scim:api:messages:2.0:PatchOp"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
[{
"op":"remove", "op":"remove",
"path":"emails[type eq \"work\" and value ew \"example.com\"]" "path":"emails[type eq \"work\" and value ew \"example.com\"]"
}]
} }
Example request to remove and add a member. Some text removed for Example request to remove and add a member. Some text removed for
readability ("..."): readability ("..."):
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
[
{
"op":"remove",
"path":"members[value eq\"2819c223...919d-413861904646\"]"
},
{
"op":"add",
"path":"members",
"value": [
{
"display": "James Smith",
"$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210",
"value": "08e1d05d...473d93df9210"
}
]
}
]
]
The following example shows how to replace all the members of a group
with a different members list. Some text removed for readabilty
("..."):
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{
[ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
{
"schemas": ["urn:scim:api:messages:2.0:PatchOp"],
"op":"remove",
"path":"members[value eq\"2819c223...919d-413861904646\"]"
},
{
"schemas": ["urn:scim:api:messages:2.0:PatchOp"],
"op":"add",
"path":"members",
"value": [
{
"display": "James Smith",
"$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210",
"value": "08e1d05d...473d93df9210"
}
]
}
]
The following example shows how to replace all the members of a group
with a different members list. Some text removed for readabilty
("..."):
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
[ [
{ "schemas": ["urn:scim:api:messages:2.0:PatchOp"],
"op":"remove","path":"members"},
{ {
"schemas": ["urn:scim:api:messages:2.0:PatchOp"], "op":"remove","path":"members"
},
{
"op":"add", "op":"add",
"path":"members", "path":"members",
"value":[ "value":[
{ {
"display": "Babs Jensen", "display": "Babs Jensen",
"$ref": "https://example.com/v2/Users/2819c223...413861904646", "$ref": "https://example.com/v2/Users/2819c223...413861904646",
"value": "2819c223-7f76-453a-919d-413861904646" "value": "2819c223-7f76-453a-919d-413861904646"
}, },
{ {
"display": "James Smith", "display": "James Smith",
"$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210",
"value": "08e1d05d-121c-4561-8b96-473d93df9210" "value": "08e1d05d-121c-4561-8b96-473d93df9210"
}] }]
} }
] ]
]
3.3.2.3. Replace Operation 3.3.2.3. Replace Operation
The "replace" operation replaces the value at the target location The "replace" operation replaces the value at the target location
specified by the "path". The operation performs the following specified by the "path". The operation performs the following
functions depending on the target location specified by "path" : functions depending on the target location specified by "path" :
o If the "path" parameter is omitted, the target is assumed to be
the resoruce itself. In this case, the "value" attribute SHALL
contain a list of one or more attributes that are to be replaced.
o If the target location is a single-value attribute, the attributes o If the target location is a single-value attribute, the attributes
value is replaced. value is replaced.
o If the target location is a multi-valued attribute and no filter o If the target location is a multi-valued attribute and no filter
is specified, the attribute and all values are replaced. is specified, the attribute and all values are replaced.
o If the target location specifies a complex attribute, a set of
sub-attributes SHALL be specified in the "value" parameter which
replaces any existing values or adds where an attribute did not
previously exist. Sub-attributes that are not specified in the
"value" parameter are left unchanged.
o If the target location is a multi-valued attribute and a complex o If the target location is a multi-valued attribute and a complex
filter is specified comparing a "value", the values matched by the filter is specified comparing a "value", the values matched by the
filter are replaced. filter are replaced.
o If the target location is a complex-multi-valued attribute and a o If the target location is a complex-multi-valued attribute and a
complex filter is specified based on the attribute's sub- complex filter is specified based on the attribute's sub-
attributes, the matching records are replaced. attributes, the matching records are replaced.
o If the target location is a complex-multi-valued attribute with a o If the target location is a complex-multi-valued attribute with a
complex filter and a specific sub-attribute (e.g. "addresses[type complex filter and a specific sub-attribute (e.g. "addresses[type
eq "work"].streetAddress" ), the matching sub-attribute of the eq "work"].streetAddress" ), the matching sub-attribute of the
matching record is replaced. matching record is replaced.
The following example shows how to replace all the members of a group The following example shows how to replace all the members of a group
with a different members list in a single replace operation. Some with a different members list in a single replace operation. Some
text removed for readability ("..."): text removed for readability ("..."):
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:api:messages:2.0:PatchOp"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
[{
"op":"replace", "op":"replace",
"path":"members", "path":"members",
"value":[ "value":[
{ {
"display": "Babs Jensen", "display": "Babs Jensen",
"$ref": "https://example.com/v2/Users/2819c223...413861904646", "$ref": "https://example.com/v2/Users/2819c223...413861904646",
"value": "2819c223...413861904646" "value": "2819c223...413861904646"
}, },
{ {
"display": "James Smith", "display": "James Smith",
"$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210",
"value": "08e1d05d...473d93df9210" "value": "08e1d05d...473d93df9210"
} }
] ]
} }]
}
The following example shows how to change a User's entire "work" The following example shows how to change a User's entire "work"
address. address.
PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
[{
"op":"replace",
"path":"addresses[type eq \"work\"]",
"value":
{
"type": "work",
"streetAddress": "911 Universal City Plaza",
"locality": "Hollywood",
"region": "CA",
"postalCode": "91608",
"country": "US",
"formatted": "911 Universal City Plaza\nHollywood, CA 91608 US",
"primary": true
}
}]
}
The following example shows how to change a User's "work" email
address:
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:api:messages:2.0:PatchOp"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"op":"replace", [{
"path":"addresses[type eq \"work\"]", "op":"replace",
"value": "path":"emails[type eq \"work\"].value",
{ "value":"bjenson@example.com"
"type": "work", }]
"streetAddress": "911 Universal City Plaza",
"locality": "Hollywood",
"region": "CA",
"postalCode": "91608",
"country": "US",
"formatted": "911 Universal City Plaza\nHollywood, CA 91608 US",
"primary": true
}
} }
The following example shows how to replace one or more attributes of
The following example shows how to change a User's address. Since a User resource.
address does not have a value Sub-Attribute, the existing address
must be removed and the modified address added.
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
{ {
"schemas": ["urn:scim:api:messages:2.0:PatchOp"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"op":"replace", [{
"path":"addresses[type eq \"work\"].streetAddress", "op":"replace",
"value":"911 Universal City Plaza" "value":"{
"emails":[
{
"value":"bjensen@example.com",
"type":"work",
"primary":true
},
{
"value":"babs@jensen.org",
"type":"home"
}
],
"nickname":"Babs"
}]
} }
3.4. Deleting Resources 3.4. Deleting Resources
Clients request resource removal via DELETE. Service providers MAY Clients request resource removal via DELETE. Service providers MAY
choose not to permanently delete the resource, but MUST return a 404 choose not to permanently delete the resource, but MUST return a 404
error code for all operations associated with the previously deleted error code for all operations associated with the previously deleted
Id. Service providers MUST also omit the resource from future query Id. Service providers MUST also omit the resource from future query
results. In addition the service provider SHOULD NOT consider the results. In addition the service provider SHOULD NOT consider the
deleted resource in conflict calculation. For example if a User deleted resource in conflict calculation. For example if a User
skipping to change at page 36, line 39 skipping to change at page 40, line 22
GET /Users/2819c223-7f76-453a-919d-413861904646 GET /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Server Response: Server Response:
HTTP/1.1 404 NOT FOUND HTTP/1.1 404 NOT FOUND
{ {
"schemas": ["urn:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"Errors":[ "Errors":[
{ {
"description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
"code":"404" "code":"404"
} }
] ]
} }
3.5. Bulk 3.5. Bulk
The SCIM bulk operation is an optional server feature that enables The SCIM bulk operation is an optional server feature that enables
clients to send a potentially large collection of resource operations clients to send a potentially large collection of resource operations
in a single request. The body of a a bulk operation contains a set in a single request. The body of a a bulk operation contains a set
of HTTP resource operations using one of the API supported HTTP of HTTP resource operations using one of the API supported HTTP
methods; i.e., POST, PUT, PATCH or DELETE. methods; i.e., POST, PUT, PATCH or DELETE.
Bulk requests are identified using the following URI: Bulk requests are identified using the following URI:
'urn:scim:api:messages:2.0:BulkRequest'. Bulk responses are "urn:ietf:params:scim:api:messages:2.0:BulkRequest". Bulk responses
identified using the following URI: are identified using the following URI:
'urn:scim:api:messages:2.0:BulkResponse'. Bulk requests and bulk "urn:ietf:params:scim:api:messages:2.0:BulkResponse". Bulk requests
responses share many attributes. Unless otherwise specified, each and bulk responses share many attributes. Unless otherwise
attribute below is present in both bulk requests and bulk responses. specified, each attribute below is present in both bulk requests and
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 An Integer specifying the number of errors that the failOnErrors An Integer specifying the number of errors that the
service provider will accept before the operation is terminated service provider will accept before the operation is terminated
and an error response is returned. OPTIONAL in a request. Not and an error response is returned. OPTIONAL in a request. Not
valid in a response. valid in a response.
The following Complex Multi-valued Attribute is defined in addition The following Complex Multi-valued Attribute is defined in addition
skipping to change at page 39, line 13 skipping to change at page 43, line 7
would have been used. If an error occurred the status MUST also would have been used. If an error occurred the status MUST also
include the description attribute containing a human readable include the description attribute containing a human readable
explanation of the error. explanation of the error.
"status": "201" "status": "201"
The following is an example of a status in a failed operation. The following is an example of a status in a failed operation.
"status": "400", "status": "400",
"response":{ "response":{
"schemas": ["urn:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax" "scimType":"invalidSyntax"
"detail":"Request is unparseable, syntactically incorrect, or violates schema.", "detail":"Request is unparseable, syntactically incorrect, or violates schema.",
"status":"400" "status":"400"
} }
The following example shows how to add, update, and remove a user. The following example shows how to add, update, and remove a user.
The failOnErrors attribute is set to '1' indicating the service The failOnErrors attribute is set to '1' indicating the service
provider should return on the first error. The POST operation's provider should return on the first error. The POST operation's
bulkId value is set to 'qwerty' enabling the client to match the new bulkId value is set to 'qwerty' enabling the client to match the new
User with the returned resource id '92b725cd-9465-4e7d- User with the returned resource id '92b725cd-9465-4e7d-
8c16-01f8e146b87a'. 8c16-01f8e146b87a'.
POST /v2/Bulk POST /v2/Bulk
Host: example.com Host: example.com
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:scim:api:messages:2.0:BulkRequest"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"failOnErrors":1, "failOnErrors":1,
"Operations":[ "Operations":[
{ {
"method":"POST", "method":"POST",
"path":"/Users", "path":"/Users",
"bulkId":"qwerty", "bulkId":"qwerty",
"data":{ "data":{
"schemas": ["urn:scim:api:messages:2.0:User"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:User"],
"userName":"Alice" "userName":"Alice"
} }
}, },
{ {
"method":"PUT", "method":"PUT",
"path":"/Users/b7c14771-226c-4d05-8860-134711653041", "path":"/Users/b7c14771-226c-4d05-8860-134711653041",
"version":"W\/\"3694e05e9dff591\"", "version":"W\/\"3694e05e9dff591\"",
"data":{ "data":{
"schemas": ["urn:scim:api:messages:2.0:User"], "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"b7c14771-226c-4d05-8860-134711653041", "id":"b7c14771-226c-4d05-8860-134711653041",
"userName":"Bob" "userName":"Bob"
} }
}, },
{ {
"method": "PATCH", "method": "PATCH",
"path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", "path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"version": "W/\"edac3253e2c0ef2\"", "version": "W/\"edac3253e2c0ef2\"",
"data": {[ "data": {[
{ {
skipping to change at page 41, line 9 skipping to change at page 45, line 9
} }
] ]
} }
The service provider returns the following response. The service provider returns the following response.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
{ {
"schemas": ["urn:scim:api:messages:2.0:BulkResponse"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [ "Operations": [
{ {
"location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST", "method": "POST",
"bulkId": "qwerty", "bulkId": "qwerty",
"version": "W\/\"oY4m4wn58tkVjJxK\"", "version": "W\/\"oY4m4wn58tkVjJxK\"",
"status": "201" "status": "201"
}, },
{ {
"location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
skipping to change at page 42, line 9 skipping to change at page 46, line 9
The following response is returned if an error occurred when The following response is returned if an error occurred when
attempting to create the User 'Alice'. The service provider stops attempting to create the User 'Alice'. The service provider stops
processing the bulk operation and immediately returns a response to processing the bulk operation and immediately returns a response to
the client. The response contains the error and any successful the client. The response contains the error and any successful
results prior to the error. results prior to the error.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
{ {
"schemas": ["urn:scim:api:messages:2.0:BulkResponse"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"bulkId": "qwerty", "bulkId": "qwerty",
"status": "400", "status": "400",
"response":{ "response":{
"schemas": ["urn:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax" "scimType":"invalidSyntax"
"detail":"Request is unparseable, syntactically incorrect, or violates schema.", "detail":"Request is unparseable, syntactically incorrect, or violates schema.",
"status":"400" "status":"400"
} }
} }
] ]
} }
If the failOnErrors attribute is not specified or the service If the failOnErrors attribute is not specified or the service
provider has not reached the error limit defined by the client the provider has not reached the error limit defined by the client the
service provider will continue to process all operations. The service provider will continue to process all operations. The
following is an example in which all operations failed. following is an example in which all operations failed.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
{ {
"schemas": ["urn:scim:api:messages:2.0:BulkResponse"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"bulkId": "qwerty", "bulkId": "qwerty",
"status": "400", "status": "400",
"response":{ "response":{
"schemas": ["urn:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax" "scimType":"invalidSyntax"
"detail":"Request is unparseable, syntactically incorrect, or violates schema.", "detail":"Request is unparseable, syntactically incorrect, or violates schema.",
"status":"400" "status":"400"
} }
}, },
{ {
"location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT", "method": "PUT",
"status": "412", "status": "412",
"response":{ "response":{
"schemas": ["urn:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Failed to update as user changed on the server since you last retrieved it.", "detail":"Failed to update as user changed on the server since you last retrieved it.",
"status":"412" "status":"412"
} }
}, },
{ {
"location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH", "method": "PATCH",
"status": "412", "status": "412",
"response":{ "response":{
"schemas": ["urn:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Failed to update as user changed on the server since you last retrieved it.", "detail":"Failed to update as user changed on the server since you last retrieved it.",
"status":"412" "status":"412"
} }
}, },
{ {
"location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE", "method": "DELETE",
"status": "404", "status": "404",
"response":{ "response":{
"schemas": ["urn: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"
} }
} }
] ]
} }
The client can, within one bulk operation, create a new User, a new The client can, within one bulk operation, create a new User, a new
Group and add the newly created User to the newly created Group. In Group and add the newly created User to the newly created Group. In
order to add the new User to the Group the client must use the order to add the new User to the Group the client must use the
skipping to change at page 44, line 13 skipping to change at page 48, line 13
Group with the displayName 'Tour Guides' with Alice as a member. Group with the displayName 'Tour Guides' with Alice as a member.
POST /v2/Bulk POST /v2/Bulk
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
{ {
"schemas": ["urn:scim:api:messages:2.0:BulkRequest"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"path": "/Users", "path": "/Users",
"bulkId": "qwerty", "bulkId": "qwerty",
"data": { "data": {
"schemas": ["urn:scim:schemas:core:2.0:User"], "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "Alice" "userName": "Alice"
} }
}, },
{ {
"method": "POST", "method": "POST",
"path": "/Groups", "path": "/Groups",
"bulkId": "ytrewq", "bulkId": "ytrewq",
"data": { "data": {
"schemas": ["urn:scim:schemas:core:2.0:Group"], "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Tour Guides", "displayName": "Tour Guides",
"members": [ "members": [
{ {
"type": "User", "type": "User",
"value": "bulkId:qwerty" "value": "bulkId:qwerty"
} }
] ]
} }
} }
] ]
} }
The service provider returns the following response. The service provider returns the following response.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
{ {
"schemas": ["urn:scim:api:messages:2.0:BulkResponse"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [ "Operations": [
{ {
"location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST", "method": "POST",
"bulkId": "qwerty", "bulkId": "qwerty",
"version": "W\/\"4weymrEsh5O6cAEK\"", "version": "W\/\"4weymrEsh5O6cAEK\"",
"status": "201" "status": "201"
}, },
{ {
"location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
skipping to change at page 46, line 11 skipping to change at page 50, line 11
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
ETag: W/"lha5bbazU3fNvfe5" ETag: W/"lha5bbazU3fNvfe5"
{ {
"schemas": ["urn:scim:schemas:core:2.0:Group"], "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "e9e30dba-f08f-4109-8486-d5c6a331660a", "id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
"displayName": "Tour Guides", "displayName": "Tour Guides",
"meta": { "meta": {
"resourceType": "Group", "resourceType": "Group",
"created": "2011-08-01T18:29:49.793Z", "created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T20:31:02.315Z", "lastModified": "2011-08-01T20:31:02.315Z",
"location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"version": "W\/\"lha5bbazU3fNvfe5\"" "version": "W\/\"lha5bbazU3fNvfe5\""
}, },
"members": [ "members": [
skipping to change at page 47, line 5 skipping to change at page 51, line 5
"type": "User" "type": "User"
} }
] ]
} }
Extensions that include references to other resources MUST be handled Extensions that include references to other resources MUST be handled
in the same way by the service provider. The following example uses in the same way by the service provider. The following example uses
the bulkId attribute within the enterprise extension managerId the bulkId attribute within the enterprise extension managerId
attribute. attribute.
POST /v2/Bulk POST /v2/Bulk
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
{ {
"schemas": ["urn:scim:api:messages:2.0:BulkRequest"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"path": "/Users", "path": "/Users",
"bulkId": "qwerty", "bulkId": "qwerty",
"data": { "data": {
"schemas": ["urn:scim:schemas:core:2.0:User"], "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "Alice" "userName": "Alice"
} }
}, },
{ {
"method": "POST", "method": "POST",
"path": "/Users", "path": "/Users",
"bulkId": "ytrewq", "bulkId": "ytrewq",
"data": { "data": {
"schemas": [ "schemas": [
"urn:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:core:2.0:User",
"urn:scim:schemas:extension:enterprise:2.0:User" "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
], ],
"userName": "Bob", "userName": "Bob",
"urn:scim:schemas:extension:enterprise:2.0:User": { "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "11250", "employeeNumber": "11250",
"manager": { "manager": {
"managerId": "batchId:qwerty", "managerId": "batchId:qwerty",
"displayName": "Alice" "displayName": "Alice"
}
} }
} }
} }
] }
} ]
}
The service provider MUST try to resolve circular cross references The service provider MUST try to resolve circular cross references
between resources in a single bulk job but MAY stop after a failed between resources in a single bulk job but MAY stop after a failed
attempt and instead return the status code 409 Conflict. The attempt and instead return the status code 409 Conflict. The
following example exhibits the potential conflict. following example exhibits the potential conflict.
POST /v2/Bulk POST /v2/Bulk
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
{ {
"schemas": ["urn:scim:api:messages:2.0:BulkRequest"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"path": "/Groups", "path": "/Groups",
"bulkId": "qwerty", "bulkId": "qwerty",
"data": { "data": {
"schemas": ["urn:scim:schemas:core:2.0:Group"], "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group A", "displayName": "Group A",
"members": [ "members": [
{ {
"type": "Group", "type": "Group",
"value": "bulkId:ytrewq" "value": "bulkId:ytrewq"
} }
] ]
} }
}, },
{ {
"method": "POST", "method": "POST",
"path": "/Groups", "path": "/Groups",
"bulkId": "ytrewq", "bulkId": "ytrewq",
"data": { "data": {
"schemas": ["urn:scim:schemas:core:2.0:Group"], "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group B", "displayName": "Group B",
"members": [ "members": [
{ {
"type": "Group", "type": "Group",
"value": "bulkId:qwerty" "value": "bulkId:qwerty"
} }
] ]
} }
} }
] ]
skipping to change at page 50, line 9 skipping to change at page 54, line 9
GET /v2/Groups?filter=displayName sw 'Group' GET /v2/Groups?filter=displayName sw 'Group'
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
{ {
"schemas": ["urn:scim:api:messages:2.0:ListResponse"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 2, "totalResults": 2,
"Resources": [ "Resources": [
{ {
"id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"schemas": ["urn:scim:schemas:core:2.0:Group"], "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group A", "displayName": "Group A",
"meta": { "meta": {
"resourceType": "Group", "resourceType": "Group",
"created": "2011-08-01T18:29:49.793Z", "created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T18:29:51.135Z", "lastModified": "2011-08-01T18:29:51.135Z",
"location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", "location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"version": "W\/\"mvwNGaxB5SDq074p\"" "version": "W\/\"mvwNGaxB5SDq074p\""
}, },
"members": [ "members": [
{ {
"value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", "$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"type": "Group" "type": "Group"
} }
] ]
}, },
{ {
"id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"schemas": ["urn:scim:schemas:core:2.0:Group"], "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group B", "displayName": "Group B",
"meta": { "meta": {
"resourceType": "Group", "resourceType": "Group",
"created": "2011-08-01T18:29:50.873Z", "created": "2011-08-01T18:29:50.873Z",
"lastModified": "2011-08-01T18:29:50.873Z", "lastModified": "2011-08-01T18:29:50.873Z",
"location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", "location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"version": "W\/\"wGB85s2QJMjiNnuI\"" "version": "W\/\"wGB85s2QJMjiNnuI\""
}, },
"members": [ "members": [
{ {
skipping to change at page 51, line 26 skipping to change at page 55, line 26
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: 4294967296 Content-Length: 4294967296
... ...
HTTP/1.1 413 Request Entity Too Large HTTP/1.1 413 Request Entity Too Large
Content-Type: application/scim+json Content-Type: application/scim+json
{ {
"schemas":["urn:scim:api:messages:2.0:Error"], "schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],
"status": "413", "status": "413",
"detail":"The size of the bulk operation exceeds the maxPayloadSize (1048576)." "detail":"The size of the bulk operation exceeds the maxPayloadSize (1048576)."
} }
3.6. Data Input/Output Formats 3.6. Data Input/Output Formats
Servers MUST accept requests and respond with JSON structured Servers MUST accept requests and respond with JSON structured
responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default
encoding format. encoding format.
skipping to change at page 53, line 20 skipping to change at page 57, line 20
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: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"a330bc54f0671c9" ETag: W/"a330bc54f0671c9"
{ {
"schemas":["urn: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":{ "meta":{
"resourceType": "User", "resourceType": "User",
"created":"2011-08-01T18:29:49.793Z", "created":"2011-08-01T18:29:49.793Z",
"lastModified":"2011-08-01T18:29:49.793Z", "lastModified":"2011-08-01T18:29:49.793Z",
"location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"a330bc54f0671c9\"" "version":"W\/\"a330bc54f0671c9\""
} }
} }
3.8. Attribute Notation 3.8. Attribute Notation
All operations share a common scheme for referencing simple and All operations share a common scheme for referencing simple and
complex attributes. In general, attributes are identified by complex attributes. In general, attributes are identified by
prefixing the attribute name with its schema URN separated by a ':' prefixing the attribute name with its schema URN separated by a ':'
character; e.g., the core User resource attribute 'userName' is character; e.g., the core User resource attribute 'userName' is
identified as 'urn:scim:schemas:core:2.0:User:userName'. Clients MAY identified as "urn:ietf:params:scim:schemas:core:2.0:User:userName".
omit core schema attribute URN prefixes though MUST fully qualify Clients MAY omit core schema attribute URN prefixes though MUST fully
extended attributes with the associated resource URN; e.g., the qualify extended attributes with the associated resource URN; e.g.,
attribute 'age' defined in 'urn:scim:schemas:exampleCo:2.0:hr' is the attribute 'age' defined in
fully encoded as 'urn:scim:schemas:exampleCo:2.0:hr:age'. A Complex "urn:ietf:params:scim:schemas:exampleCo:2.0:hr" is fully encoded as
"urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age". A Complex
attributes' Sub-Attributes are referenced via nested, dot ('.') attributes' Sub-Attributes are referenced via nested, dot ('.')
notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For
example, the fully qualified path for a User's givenName is example, the fully qualified path for a User's givenName is
urn:scim:schemas:core:2.0:User:name.givenName All facets (URN, "urn:ietf:params:scim:schemas:core:2.0:User:name.givenName" All
attribute and Sub-Attribute name) of the fully encoded Attribute name facets (URN, attribute and Sub-Attribute name) of the fully encoded
are case insensitive. Attribute name are case insensitive.
3.9. "/Me" Authenticated Subject Alias 3.9. "/Me" Authenticated Subject Alias
A client MAY use a URL of the form "<base-URI>/Me" as a URI alias for A client MAY use a URL of the form "<base-URI>/Me" as a URI alias for
the User or other resource associated with the currently the User or other resource associated with the currently
authenticated subject for any SCIM operation. A service provider MAY authenticated subject for any SCIM operation. A service provider MAY
respond in ONE of 3 ways: respond in ONE of 3 ways:
o A service provider that does NOT support this feature SHOULD o A service provider that does NOT support this feature SHOULD
respond with status 403 (FORBIDDEN). respond with status 403 (FORBIDDEN).
skipping to change at page 54, line 33 skipping to change at page 58, line 33
subject. subject.
3.10. HTTP Status and Error Response Handling 3.10. HTTP Status and Error Response Handling
The SCIM Protocol uses the HTTP status response status codes defined The SCIM Protocol uses the HTTP status response status codes defined
in Section 6 [RFC7231] to indicate operation success or failure. In in Section 6 [RFC7231] to indicate operation success or failure. In
addition to returning a HTTP response code implementers MUST return addition to returning a HTTP response code implementers MUST return
the errors in the body of the response in the client requested format the errors in the body of the response in the client requested format
containing the error response and, per the HTTP specification, human- containing the error response and, per the HTTP specification, human-
readable explanations. Error responses are identified using the readable explanations. Error responses are identified using the
following "schema" URI: "urn:scim:api:messages:2.0:Error". The following "schema" URI:
following attributes are defined for a SCIM error response using a "urn:ietf:params:scim:api:messages:2.0:Error". The following
JSON body: attributes are defined for a SCIM error response using a JSON body:
status status
The HTTP status code (see Section 6 [RFC7231]). REQUIRED The HTTP status code (see Section 6 [RFC7231]). REQUIRED
scimType scimType
A SCIM detailed error keyword. See Table 8. OPTIONAL A SCIM detailed error keyword. See Table 8. OPTIONAL
detail detail
A detailed, human readable message. OPTIONAL A detailed, human readable message. OPTIONAL
skipping to change at page 57, line 35 skipping to change at page 61, line 35
Note that in the table above (Table 8), the applicability table Note that in the table above (Table 8), the applicability table
applies to the normal HTTP method but MAY apply within a SCIM Bulk applies to the normal HTTP method but MAY apply within a SCIM Bulk
operation (via HTTP POST). operation (via HTTP POST).
Error example in response to a non-existent GET request. Error example in response to a non-existent GET request.
HTTP/1.1 404 NOT FOUND HTTP/1.1 404 NOT FOUND
{ {
"schemas": ["urn:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found", "detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
"status":"404 "status":"404
} }
Error example in response to a PUT request. Error example in response to a PUT request.
HTTP/1.1 400 BAD REQUEST HTTP/1.1 400 BAD REQUEST
{ {
"schemas": ["urn: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"
} }
[[Editor's note: while the detail error codes seem to have consensus, [[Editor's note: while the detail error codes seem to have consensus,
there is a question about whether the error codes should be there is a question about whether the error codes should be
extensible so that individual service providers may define site extensible so that individual service providers may define site
specific codes. Should all scimTypes be URIs, so that scimTypes can specific codes. Should all scimTypes be URIs, so that scimTypes can
be registered via IANA? Should there be a separate field defined for be registered via IANA? Should there be a separate field defined for
skipping to change at page 59, line 12 skipping to change at page 63, line 12
Example: Example:
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:scim:schemas:core:2.0:User"], "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName":"bjensen", "userName":"bjensen",
"externalId":"bjensen", "externalId":"bjensen",
"name":{ "name":{
"formatted":"Ms. Barbara J Jensen III", "formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen", "familyName":"Jensen",
"givenName":"Barbara" "givenName":"Barbara"
} }
} }
The server responds with an ETag in the response header and meta The server responds with an ETag in the response header and meta
structure. structure.
HTTP/1.1 201 Created HTTP/1.1 201 Created
Content-Type: application/scim+json Content-Type: application/scim+json
Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1" ETag: W/"e180ee84f0671b1"
{ {
"schemas":["urn: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",
"meta":{ "meta":{
"resourceType":"User", "resourceType":"User",
"created":"2011-08-01T21:32:44.882Z", "created":"2011-08-01T21:32:44.882Z",
"lastModified":"2011-08-01T21:32:44.882Z", "lastModified":"2011-08-01T21:32:44.882Z",
"location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"e180ee84f0671b1\"" "version":"W\/\"e180ee84f0671b1\""
}, },
"name":{ "name":{
"formatted":"Ms. Barbara J Jensen III", "formatted":"Ms. Barbara J Jensen III",
skipping to change at page 63, line 8 skipping to change at page 67, line 8
Servers that receive HTTP GET requests using filters that contain Servers that receive HTTP GET requests using filters that contain
restricted or confidential information SHOULD respond with HTTP restricted or confidential information SHOULD respond with HTTP
status 403 indicating the operation is FORBIDDEN. A detailed error, status 403 indicating the operation is FORBIDDEN. A detailed error,
"confidential_restricted" may be returned indicating the request must "confidential_restricted" may be returned indicating the request must
be submitted using POST. A non-normative example: be submitted using POST. A non-normative example:
HTTP/1.1 403 FORBIDDEN HTTP/1.1 403 FORBIDDEN
{ {
"schemas": ["urn:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"Errors":[ "Errors":[
{ {
"description":"Query filter involving 'name' is restricted or confidential", "description":"Query filter involving 'name' is restricted or confidential",
"error":"confidential_restricted" "error":"confidential_restricted"
} }
] ]
} }
6.3. HTTP Considerations 6.3. HTTP Considerations
skipping to change at page 65, line 40 skipping to change at page 69, line 40
Restrictions on usage: For most client types, it is sufficient to Restrictions on usage: For most client types, it is sufficient to
recognize the content as equivalent to "application/json". recognize the content as equivalent to "application/json".
Applications intending to use SCIM protocol SHOULD use the Applications intending to use SCIM protocol SHOULD use the
application/scim+json media type. application/scim+json media type.
Author: Phil Hunt Author: Phil Hunt
Change controller: IETF Change controller: IETF
7.2. SCIM API Message Schema Registry 7.2. SCIM Message URI Registry
As per the IANA SCIM Schema Registry in [I-D.ietf-scim-core-schema], As per the IANA SCIM Schema Registry in [I-D.ietf-scim-core-schema],
the following registers and extends the SCIM Schema Registry to the following registers and extends the SCIM Schema Registry to
define SCIM protocol request/response JSON schema URN identifier define SCIM protocol request/response JSON schema URN identifier
prefix of "urn:scim:api:messages:2.0" which is part of the URN sub- prefix of "urn:ietf:params:scim:api:messages:2.0" which is part of
Namespace for SCIM. There is no specific associated resource type. the URN sub-Namespace for SCIM. There is no specific associated
resource type.
+---------------------------------------+-----------+---------------+ +---------------------------------+-----------------+---------------+
| Schema URI | Name | Reference | | Schema URI | Name | Reference |
+---------------------------------------+-----------+---------------+ +---------------------------------+-----------------+---------------+
| urn:scim:api:messages:2.0:ListRespons | List/Quer | See Section | | urn:ietf:params:scim:api: | List/Query | See Section |
| e | y | 3.2.2 | | messages:2.0:ListResponse | Response | 3.2.2 |
| | Response | | | urn:ietf:params:scim:api: | POST Query | See Section |
| urn:scim:api:messages:2.0:SearchReque | POST | See Section | | messages:2.0:SearchRequest | Request | 3.2.3 |
| st | Query | 3.2.3 | | urn:ietf:params:scim:api: | Patch Operation | See Section |
| | Request | | | messages:2.0:PatchOp | | 3.3.2 |
| urn:scim:api:messages:2.0:PatchOp | Patch | See Section | | urn:ietf:params:scim:api: | Bulk Operations | See Section |
| | Operation | 3.3.2 | | messages:2.0:BulkRequest | Request | 3.5 |
| urn:scim:api:messages:2.0:BulkRequest | Bulk Oper | See Section | | urn:ietf:params:scim:api: | Bulk Operations | See Section |
| | ations | 3.5 | | messages:2.0:BulkResponse | Response | 3.5 |
| | Request | | | urn:ietf:params:scim:api: | Error Response | See Section |
| urn:scim:api:messages:2.0:BulkRespons | Bulk Oper | See Section | | messages:2.0:Error | | 3.10 |
| e | ations | 3.5 | +---------------------------------+-----------------+---------------+
| | Response | |
| urn:scim:api:messages:2.0:Error | Error | See Section |
| | Response | 3.10 |
+---------------------------------------+-----------+---------------+
SCIM Schema URIs for Data Resources Table 9: SCIM Schema URIs for Data Resources
8. References 8. References
8.1. Normative References 8.1. Normative References
[I-D.ietf-precis-saslprepbis] [I-D.ietf-precis-saslprepbis]
Saint-Andre, P. and A. Melnikov, "Preparation and Saint-Andre, P. and A. Melnikov, "Preparation and
Comparison of Internationalized Strings Representing Comparison of Internationalized Strings Representing
Usernames and Passwords", draft-ietf-precis-saslprepbis-07 Usernames and Passwords", draft-ietf-precis-saslprepbis-07
(work in progress), March 2014. (work in progress), March 2014.
[I-D.ietf-scim-core-schema] [I-D.ietf-scim-core-schema]
Grizzle, K., Hunt, P., Wahlstroem, E., and C. Mortimore, Grizzle, K., Hunt, P., 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-06 (work in Schema", draft-ietf-scim-core-schema-08 (work in
progress), June 2014. progress), August 2014.
[IANA.Language] [IANA.Language]
Internet Assigned Numbers Authority (IANA), "Language Internet Assigned Numbers Authority (IANA), "Language
Subtag Registry", 2005. Subtag Registry", 2005.
[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.
[RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
RFC 2246, January 1999. RFC 2246, January 1999.
skipping to change at page 71, line 15 skipping to change at page 75, line 15
- Replaced the word "search" with "query" for consistency - Replaced the word "search" with "query" for consistency
- Clarified sucessful resource creation response - Clarified sucessful resource creation response
- Added clarification on primary value handling in PATCH - Added clarification on primary value handling in PATCH
(consistent with draft 03) (consistent with draft 03)
- Revised SCIM Bullk error handling to conform with draft 07 error - Revised SCIM Bullk error handling to conform with draft 07 error
handling handling
Draft 09 - PH - Revisions as follows
- Aligned API with new URN namespace per RFC3553 and IETF90
meeting
- Clarified URN usage within patch (what schema urn applies)
- Made 'path' optional in PATCH for Add and Replace
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. 106 change blocks. 
316 lines changed or deleted 440 lines changed or added

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