draft-ietf-scim-api-11.txt   draft-ietf-scim-api-12.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: March 21, 2015 SailPoint Expires: April 23, 2015 SailPoint
M. Ansari M. Ansari
Cisco Cisco
E. Wahlstroem E. Wahlstroem
Nexus Technology Nexus Technology
C. Mortimore C. Mortimore
Salesforce Salesforce
September 17, 2014 October 20, 2014
System for Cross-Domain Identity Management: Protocol System for Cross-Domain Identity Management: Protocol
draft-ietf-scim-api-11 draft-ietf-scim-api-12
Abstract Abstract
The System for Cross-Domain Identity Management (SCIM) specification The System for Cross-Domain Identity Management (SCIM) specification
is an HTTP based protocol that makes managing identities in multi- is an HTTP based protocol that makes managing identities in multi-
domain scenarios easier to support through a standardized services. domain scenarios easier to support through a standardized services.
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 March 21, 2015. This Internet-Draft will expire on April 23, 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 40 skipping to change at page 2, line 40
3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 8 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 8
3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 9 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 9
3.2.2. Query Resources . . . . . . . . . . . . . . . . . . . 10 3.2.2. Query Resources . . . . . . . . . . . . . . . . . . . 10
3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 21 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 21
3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 24 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 24
3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 25 3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 25
3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 27 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 27
3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 40 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 40
3.5. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 41 3.5. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 41
3.5.1. Circular Reference Processing . . . . . . . . . . . . 43 3.5.1. Circular Reference Processing . . . . . . . . . . . . 43
3.5.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 47 3.5.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 46
3.5.3. Response and Error Handling . . . . . . . . . . . . . 51 3.5.3. Response and Error Handling . . . . . . . . . . . . . 50
3.5.4. Maximum Operations . . . . . . . . . . . . . . . . . 57 3.5.4. Maximum Operations . . . . . . . . . . . . . . . . . 56
3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 58 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 57
3.7. Additional Operation Response Parameters . . . . . . . . 59 3.7. Additional Operation Response Parameters . . . . . . . . 58
3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 60 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 59
3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 60 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 59
3.10. HTTP Status and Error Response Handling . . . . . . . . . 61 3.10. HTTP Status and Error Response Handling . . . . . . . . . 60
3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 65 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 64
3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 65 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 64
4. Preparation and Comparison of Internationalized Strings . . . 67 4. Preparation and Comparison of Internationalized Strings . . . 66
5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 67 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 66
5.1. Associating Clients to Tenants . . . . . . . . . . . . . 68 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 67
5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 68 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 68
6. Security Considerations . . . . . . . . . . . . . . . . . . . 69 6. Security Considerations . . . . . . . . . . . . . . . . . . . 68
6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 69 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 68
6.2. Disclosure of Sensitive Information in URIs . . . . . . . 69 6.2. Disclosure of Sensitive Information in URIs . . . . . . . 68
6.3. Anonymous Requests . . . . . . . . . . . . . . . . . . . 70 6.3. Anonymous Requests . . . . . . . . . . . . . . . . . . . 69
6.4. HTTP Considerations . . . . . . . . . . . . . . . . . . . 70 6.4. HTTP Considerations . . . . . . . . . . . . . . . . . . . 69
6.5. Secure Storage and Handling of Sensitive Data . . . . . . 71 6.5. Secure Storage and Handling of Sensitive Data . . . . . . 70
6.6. Case Insensitive Comparision & International Languages . 71 6.6. Case Insensitive Comparision & International Languages . 71
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 72 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 71
7.1. Media Type Registration . . . . . . . . . . . . . . . . . 72 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 71
7.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 73 7.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 72
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 73 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 73
8.1. Normative References . . . . . . . . . . . . . . . . . . 73 8.1. Normative References . . . . . . . . . . . . . . . . . . 73
8.2. Informative References . . . . . . . . . . . . . . . . . 75 8.2. Informative References . . . . . . . . . . . . . . . . . 74
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 76 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 74
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 76 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 74
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 76 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 75
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 78
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 5 skipping to change at page 4, line 5
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
line-wrapping for readability and space limitations. Similarly, some
URI's contained within examples, have been shortened for space and
readability reasons.
1.3. Definitions 1.3. Definitions
Base URI Base URI
The SCIM HTTP protocol is described in terms of a path relative to The SCIM HTTP protocol is described in terms of a path relative to
a Base URI. The Base URI MUST NOT contain a query string as a Base URI. The Base URI MUST NOT contain a query string as
clients may append additional path information and query clients may append additional path information and query
parameters as part of forming the request. The base URI most parameters as part of forming the request. The base URI most
often is a URL which most often consists of the "https" protocol often is a URL which most often consists of the "https" protocol
scheme, a domain name and some initial path [RFC3986]. Example: scheme, a domain name and some initial path [RFC3986]. Example:
"https://example.com/scim/" "https://example.com/scim/"
skipping to change at page 8, line 8 skipping to change at page 8, line 8
"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:
ETag: W/"e180ee84f0671b1" https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1"
{ {
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646", "id":"2819c223-7f76-453a-919d-413861904646",
"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":
"version":"W\/\"e180ee84f0671b1\"" "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
}, "version":"W\/\"e180ee84f0671b1\""
"name":{ },
"formatted":"Ms. Barbara J Jensen III", "name":{
"familyName":"Jensen", "formatted":"Ms. Barbara J Jensen III",
"givenName":"Barbara" "familyName":"Jensen",
}, "givenName":"Barbara"
"userName":"bjensen" },
} "userName":"bjensen"
}
3.1.1. Resource Types 3.1.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, "/Users"
will set "resourceType" to "User", and "/Groups" will set will set "resourceType" to "User", and "/Groups" will set
"resourceType" to "Group". "resourceType" to "Group".
3.2. Retrieving Resources 3.2. Retrieving Resources
skipping to change at page 10, line 5 skipping to change at page 10, line 5
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
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:
ETag: W/"f250dd84f0671c3" https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"f250dd84f0671c3"
{ {
"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",
"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":
"version":"W\/\"f250dd84f0671c3\"" "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
}, "version":"W\/\"f250dd84f0671c3\""
"name":{ },
"formatted":"Ms. Barbara J Jensen III", "name":{
"familyName":"Jensen", "formatted":"Ms. Barbara J Jensen III",
"givenName":"Barbara" "familyName":"Jensen",
}, "givenName":"Barbara"
"userName":"bjensen", },
"phoneNumbers":[ "userName":"bjensen",
{ "phoneNumbers":[
"value":"555-555-8377", {
"type":"work" "value":"555-555-8377",
} "type":"work"
], }
"emails":[ ],
{ "emails":[
"value":"bjensen@example.com", {
"type":"work" "value":"bjensen@example.com",
} "type":"work"
] }
} ]
}
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.
skipping to change at page 18, line 29 skipping to change at page 18, line 29
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:ietf:params: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
skipping to change at page 20, line 14 skipping to change at page 20, line 14
+------------+----------------------------+-------------------------+ +------------+----------------------------+-------------------------+
| Parameter | Description | Default | | Parameter | Description | Default |
+------------+----------------------------+-------------------------+ +------------+----------------------------+-------------------------+
| startIndex | The 1-based index of the | 1 | | startIndex | The 1-based index of the | 1 |
| | first query result. A | | | | first query result. A | |
| | value less than 1 SHALL be | | | | value less than 1 SHALL be | |
| | interpreted as 1. | | | | interpreted as 1. | |
| count | Non-negative Integer. | None. When specified | | count | Non-negative Integer. | None. When specified |
| | Specifies the desired | the service provider | | | Specifies the desired | the service provider |
| | maximum number of query | MUST not return more | | | maximum number of query | MUST NOT return more |
| | results per page; e.g., | results than specified | | | results per page; e.g., | results than specified |
| | 10. A negative value SHALL | though MAY return fewer | | | 10. A negative value 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 5: Pagination Request parameters
skipping to change at page 23, line 8 skipping to change at page 23, line 8
count An integer indicating the desired maximum number of query count An integer indicating the desired maximum number of query
results per page. See pagination (Section 3.2.2.4). OPTIONAL. results per page. See pagination (Section 3.2.2.4). OPTIONAL.
After receiving a HTTP POST request, a response is returned as After receiving a HTTP POST request, a response is returned as
specified in Section 3.2.2. specified in Section 3.2.2.
The following example shows an HTTP POST Query request with search The following example shows an HTTP POST Query request with search
parameters attributes, filter, and count included: parameters attributes, filter, and count included:
POST /.search POST /.search
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: ... Content-Length: ...
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
"attributes": ["displayName", "userName"], "attributes": ["displayName", "userName"],
"filter": "(displayName sw \"smith\") and (meta.resourceType eq \"User\")", "filter":
"startIndex": 1, "(displayName sw \"smith\") and (meta.resourceType eq \"User\")",
"count": 10 "startIndex": 1,
} "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
{ {
skipping to change at page 27, line 6 skipping to change at page 27, line 6
{ {
"value":"bjensen@example.com" "value":"bjensen@example.com"
}, },
{ {
"value":"babs@jensen.org" "value":"babs@jensen.org"
} }
] ]
} }
The service responds with the entire, updated User: The service responds with the entire, updated User:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
ETag: W/"b431af54f0671a2" ETag: W/"b431af54f0671a2"
Location:"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646" Location:
{ "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646"
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], {
"id":"2819c223-7f76-453a-919d-413861904646", "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName":"bjensen", "id":"2819c223-7f76-453a-919d-413861904646",
"externalId":"bjensen", "userName":"bjensen",
"name":{ "externalId":"bjensen",
"formatted":"Ms. Barbara J Jensen III", "name":{
"familyName":"Jensen", "formatted":"Ms. Barbara J Jensen III",
"givenName":"Barbara", "familyName":"Jensen",
"middleName":"Jane" "givenName":"Barbara",
}, "middleName":"Jane"
"emails":[ },
{ "emails":[
"value":"bjensen@example.com" {
}, "value":"bjensen@example.com"
{ },
"value":"babs@jensen.org" {
} "value":"babs@jensen.org"
], }
"meta": { ],
"resourceType":"User", "meta": {
"created":"2011-08-08T04:56:22Z", "resourceType":"User",
"lastModified":"2011-08-08T08:00:12Z", "created":"2011-08-08T04:56:22Z",
"location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", "lastModified":"2011-08-08T08:00:12Z",
"version":"W\/\"b431af54f0671a2\"" "location":
} "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
} "version":"W\/\"b431af54f0671a2\""
}
}
3.3.2. Modifying with PATCH 3.3.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. The general form
of the SCIM patch request is based on JavaScript Object Notation of the SCIM patch request is based on JavaScript Object Notation
(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.
skipping to change at page 29, line 23 skipping to change at page 29, line 23
"path":"members[value eq "path":"members[value eq
\"2819c223-7f76-453a-919d-413861904646\"]" \"2819c223-7f76-453a-919d-413861904646\"]"
"path":"members[value eq "path":"members[value eq
\"2819c223-7f76-453a-919d-413861904646\"].displayName" \"2819c223-7f76-453a-919d-413861904646\"].displayName"
Figure 7: Example Path Values Figure 7: Example Path Values
Each operation against an attribute MUST be compatible with the Each operation against an attribute MUST be compatible with the
attribute's mutability and schema as defined in the Attribute Types attribute's mutability and schema as defined in the Attribute Types
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 MUST
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 SCIM service provider's representation of "schemas" attribute on the SCIM service provider's representation of
skipping to change at page 31, line 49 skipping to change at page 32, line 5
] ]
} }
] ]
} }
If the user was already a member of this group, no changes should be If the user was already a member of this group, no changes should be
made to the resource and a success response should be returned. The made to the resource and a success response should be returned. The
server responds with either the entire updated Group or no response server responds with either the entire updated Group or no response
body: body:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
ETag: W/"b431af54f0671a2" ETag: W/"b431af54f0671a2"
Location: "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 The following example shows how to add one or more attributes to a
User resource without using a "path" attribute. User resource without using a "path" attribute.
PATCH /Users/2819c223-7f76-453a-919d-413861904646 PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9" If-Match: W/"a330bc54f0671c9"
skipping to change at page 35, line 25 skipping to change at page 35, line 25
{ {
"op":"remove", "op":"remove",
"path":"members[value eq\"2819c223...919d-413861904646\"]" "path":"members[value eq\"2819c223...919d-413861904646\"]"
}, },
{ {
"op":"add", "op":"add",
"path":"members", "path":"members",
"value": [ "value": [
{ {
"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 replace all the members of a group The following example shows how to replace all the members of a group
with a different members list. Some text removed for readabilty with a different members list. Some text removed for readabilty
("..."): ("..."):
skipping to change at page 41, line 19 skipping to change at page 41, line 19
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Example: client attempt to retrieve the previously deleted User Example: client attempt to retrieve the previously deleted User
GET /Users/2819c223-7f76-453a-919d-413861904646 GET /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com Host: example.com
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Server Response: Server Response:
HTTP/1.1 404 NOT FOUND HTTP/1.1 404 NOT FOUND
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"Errors":[
{ {
"description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"code":"404" "Errors":[
{
"description":
"Resource 2819c223-7f76-453a-919d-413861904646 not found",
"code":"404"
}
]
} }
]
}
3.5. Bulk Operations 3.5. 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. 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:
skipping to change at page 46, line 5 skipping to change at page 45, line 10
} }
If the service provider resolved the above circular references the If the service provider resolved the above circular references the
following is returned from a subsequent GET request. following is returned from a subsequent GET request.
GET /v2/Groups?filter=displayName sw 'Group' GET /v2/Groups?filter=displayName sw 'Group'
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 2,
"Resources": [
{
"id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group A",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T18:29:51.135Z",
"location":
"https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"version": "W\/\"mvwNGaxB5SDq074p\""
},
"members": [
{
"value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"$ref":
"https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"type": "Group"
}
]
},
{
"id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group B",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:50.873Z",
"lastModified": "2011-08-01T18:29:50.873Z",
"location":
"https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"version": "W\/\"wGB85s2QJMjiNnuI\""
},
"members": [
{
"value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"$ref":
"https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"type": "Group"
}
]
}
]
}
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 2,
"Resources": [
{
"id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group A",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T18:29:51.135Z",
"location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"version": "W\/\"mvwNGaxB5SDq074p\""
},
"members": [
{
"value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"type": "Group"
}
]
},
{
"id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group B",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:50.873Z",
"lastModified": "2011-08-01T18:29:50.873Z",
"location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"version": "W\/\"wGB85s2QJMjiNnuI\""
},
"members": [
{
"value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"type": "Group"
}
]
}
]
}
3.5.2. BulkdId Temporary Identifiers 3.5.2. BulkdId Temporary Identifiers
A SCIM client can, within one bulk operation, create a new "User", a A SCIM client can, within one bulk operation, create a new "User", a
new "Group" and add the newly created "User" to the newly created new "Group" and add the newly created "User" to the newly created
"Group". In order to add the new "User" to the "Group" the client "Group". In order to add the new "User" to the "Group" the client
must use the surrogate id attribute, "bulkId", to reference the User. must use the surrogate id attribute, "bulkId", to reference the User.
The "bulkId" attribute value must be pre-pended with the literal The "bulkId" attribute value must be pre-pended with the literal
"bulkId:"; e.g., if the bulkId is 'qwerty', the value is "bulkId:"; e.g., if the bulkId is 'qwerty', the value is
"bulkId:qwerty". The service provider MUST replace the string "bulkId:qwerty". The service provider MUST replace the string
"bulkId:qwerty" with the permanent resource id once created. "bulkId:qwerty" with the permanent resource id once created.
skipping to change at page 49, line 6 skipping to change at page 48, line 6
"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/json Content-Type: application/json
{ {
"schemas": ["urn:ietf:params: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":
"method": "POST", "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"bulkId": "qwerty", "method": "POST",
"version": "W\/\"4weymrEsh5O6cAEK\"", "bulkId": "qwerty",
"status": { "version": "W\/\"4weymrEsh5O6cAEK\"",
"code": "201" "status": {
} "code": "201"
}, }
{ },
"location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", {
"method": "POST", "location":
"bulkId": "ytrewq", "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"version": "W\/\"lha5bbazU3fNvfe5\"", "method": "POST",
"status": { "bulkId": "ytrewq",
"code": "201" "version": "W\/\"lha5bbazU3fNvfe5\"",
} "status": {
} "code": "201"
] }
} }
]
}
In the above example, the Alice User resource has an "id" of In the above example, the Alice User resource has an "id" of
"92b725cd-9465-4e7d-8c16-01f8e146b87a" and the Tour Guides Group has "92b725cd-9465-4e7d-8c16-01f8e146b87a" and the Tour Guides Group has
an "id" of "e9e30dba-f08f-4109-8486-d5c6a331660a". an "id" of "e9e30dba-f08f-4109-8486-d5c6a331660a".
A subsequent GET request for the 'Tour Guides' Group (with an "id" A subsequent GET request for the 'Tour Guides' Group (with an "id"
of"e9e30dba-f08f-4109-8486-d5c6a331660a") returns the following with of"e9e30dba-f08f-4109-8486-d5c6a331660a") returns the following with
Alice's "id" as the value for the member in the Group 'Tour Guides': Alice's "id" as the value for the member in the Group 'Tour Guides':
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a Location:
ETag: W/"lha5bbazU3fNvfe5" https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
ETag: W/"lha5bbazU3fNvfe5"
{ {
"schemas": ["urn:ietf:params: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":
"version": "W\/\"lha5bbazU3fNvfe5\"" "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
}, "version": "W\/\"lha5bbazU3fNvfe5\""
"members": [ },
{ "members": [
"value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", {
"$ref": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a",
"type": "User" "$ref":
} "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
] "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
skipping to change at page 52, line 14 skipping to change at page 51, line 14
attribute status MUST include the code attribute that holds the HTTP attribute status MUST include the code attribute that holds the HTTP
response code that would have been returned if a single HTTP request response code that would have been returned if a single HTTP request
would have been used. If an error occurred the status MUST also would have been used. If an error occurred the status MUST also
include the description attribute containing a human readable include the description attribute containing a human readable
explanation of the error. explanation of the error.
"status": "201" "status": "201"
The following is an example of a status in a failed operation. The following is an example of a status in a failed operation.
"status": "400", "status": "400",
"response":{ "response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax" "scimType":"invalidSyntax"
"detail":"Request is unparseable, syntactically incorrect, or violates schema.", "detail":
"status":"400" "Request is unparseable, syntactically incorrect, or violates schema.",
} "status":"400"
}
The following example shows how to add, update, and remove a user. The following example shows how to add, update, and remove a user.
The "failOnErrors" attribute is set to '1' indicating the service The "failOnErrors" attribute is set to '1' indicating the service
provider should return on the first error. The POST operation's provider should return on the first error. The POST operation's
bulkId value is set to 'qwerty' enabling the client to match the new bulkId value is set to 'qwerty' enabling the client to match the new
User with the returned resource id '92b725cd-9465-4e7d- User with the returned resource id '92b725cd-9465-4e7d-
8c16-01f8e146b87a'. 8c16-01f8e146b87a'.
POST /v2/Bulk POST /v2/Bulk
Host: example.com Host: example.com
skipping to change at page 54, line 5 skipping to change at page 53, line 5
{ {
"method":"DELETE", "method":"DELETE",
"path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"version":"W\/\"0ee8add0a938e1a\"" "version":"W\/\"0ee8add0a938e1a\""
} }
] ]
} }
The service provider returns the following response. The service provider returns the following response.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [ "Operations": [
{ {
"location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", "location":
"method": "POST", "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"bulkId": "qwerty", "method": "POST",
"version": "W\/\"oY4m4wn58tkVjJxK\"", "bulkId": "qwerty",
"status": "201" "version": "W\/\"oY4m4wn58tkVjJxK\"",
}, "status": "201"
{ },
"location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", {
"method": "PUT", "location":
"version": "W\/\"huJj29dMNgu3WXPD\"", "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
"status": "200" "method": "PUT",
}, "version": "W\/\"huJj29dMNgu3WXPD\"",
{ "status": "200"
"location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", },
"method": "PATCH", {
"version": "W\/\"huJj29dMNgu3WXPD\"", "location":
"status": "200" "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
}, "method": "PATCH",
{ "version": "W\/\"huJj29dMNgu3WXPD\"",
"location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", "status": "200"
"method": "DELETE", },
"status": "204" {
} "location":
] "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b",
} "method": "DELETE",
"status": "204"
}
]
}
The following response is returned if an error occurred when The following response is returned if an error occurred when
attempting to create the User 'Alice'. The service provider stops attempting to create the User 'Alice'. The service provider stops
processing the bulk operation and immediately returns a response to processing the bulk operation and immediately returns a response to
the client. The response contains the error and any successful the client. The response contains the error and any successful
results prior to the error. results prior to the error.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"bulkId": "qwerty", "bulkId": "qwerty",
"status": "400", "status": "400",
"response":{ "response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax" "scimType":"invalidSyntax"
"detail":"Request is unparseable, syntactically incorrect, or violates schema.", "detail":
"status":"400" "Request is unparseable, syntactically incorrect, or violates schema.",
} "status":"400"
} }
] }
} ]
}
If the "failOnErrors" attribute is not specified or the service If the "failOnErrors" attribute is not specified or the service
provider has not reached the error limit defined by the client the provider has not reached the error limit defined by the client the
service provider will continue to process all operations. The service provider will continue to process all operations. The
following is an example in which all operations failed. following is an example in which all operations failed.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/scim+json Content-Type: application/scim+json
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [ "Operations": [
{ {
"method": "POST", "method": "POST",
"bulkId": "qwerty", "bulkId": "qwerty",
"status": "400", "status": "400",
"response":{ "response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax"
"detail":"Request is unparseable, syntactically incorrect, or violates schema.",
"status":"400"
}
},
{
"location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT",
"status": "412",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Failed to update as user changed on the server since you last retrieved it.",
"status":"412"
}
},
{
"location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH",
"status": "412",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Failed to update as user changed on the server since you last retrieved it.",
"status":"412"
}
},
{
"location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE",
"status": "404",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Resource does not exist.", "scimType":"invalidSyntax"
"status":"404" "detail":
} "Request is unparseable, syntactically incorrect, or violates schema.",
} "status":"400"
] }
} },
HTTP/1.1 200 OK {
Content-Type: application/scim+json "location":
"https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT",
"status": "412",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Failed to update. Resource changed on the server.",
"status":"412"
}
},
{
"location":
"https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH",
"status": "412",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Failed to update. Resource changed on the server.",
"status":"412"
}
},
{
"location":
"https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE",
"status": "404",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Resource does not exist.",
"status":"404"
}
}
]
}
HTTP/1.1 200 OK
Content-Type: application/scim+json
{ {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [ "Operations": [
{ {
"location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", "location":
"method": "POST", "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"bulkId": "qwerty", "method": "POST",
"version": "W\/\"4weymrEsh5O6cAEK\"", "bulkId": "qwerty",
"status": "201" "version": "W\/\"4weymrEsh5O6cAEK\"",
}, "status": "201"
{ },
"location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", {
"method": "POST", "location":
"bulkId": "ytrewq", "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"version": "W\/\"lha5bbazU3fNvfe5\"", "method": "POST",
"status": "201" "bulkId": "ytrewq",
} "version": "W\/\"lha5bbazU3fNvfe5\"",
] "status": "201"
} }
]
}
3.5.4. Maximum Operations 3.5.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 8 of [I-D.ietf-scim-core-schema]). If either 'bulk' in Section 8 of [I-D.ietf-scim-core-schema]). If either
limits are exceeded the service provider MUST return the HTTP 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 58, line 8 skipping to change at page 57, line 8
Accept: application/scim+json Accept: application/scim+json
Content-Type: application/scim+json Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Content-Length: 4294967296 Content-Length: 4294967296
... ...
In response to the over-sized request, the server responds with the In response to the over-sized request, the server responds with the
following error: following error:
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:ietf:params: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.
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
skipping to change at page 60, line 4 skipping to change at page 59, line 4
notation (Section 3.8) form (e.g. userName, name, emails). notation (Section 3.8) 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
Content-Type: application/scim+json
Location:
https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"a330bc54f0671c9"
HTTP/1.1 200 OK {
Content-Type: application/scim+json "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 "id":"2819c223-7f76-453a-919d-413861904646",
ETag: W/"a330bc54f0671c9" "userName":"bjensen",
"meta":{
{ "resourceType": "User",
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], "created":"2011-08-01T18:29:49.793Z",
"id":"2819c223-7f76-453a-919d-413861904646", "lastModified":"2011-08-01T18:29:49.793Z",
"userName":"bjensen", "location":
"meta":{ "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"resourceType": "User", "version":"W\/\"a330bc54f0671c9\""
"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.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:ietf:params:scim:schemas:core:2.0:User:userName". identified as "urn:ietf:params:scim:schemas:core:2.0:User:userName".
Clients MAY omit core schema attribute URN prefixes though MUST fully Clients MAY omit core schema attribute URN prefixes though MUST fully
qualify extended attributes with the associated resource URN; e.g., qualify extended attributes with the associated resource URN; e.g.,
skipping to change at page 62, line 15 skipping to change at page 61, line 18
| | | permanent reference to the | | | | permanent reference to the |
| | | resource and SHOULD continue to | | | | resource and SHOULD continue to |
| | | use the original request URI | | | | use the original request URI |
| | | [RFC7231]. | | | | [RFC7231]. |
| 308 | GET, POST, | The client is directed to repeat | | 308 | GET, POST, | The client is directed to repeat |
| PERMANENT | PUT, PATCH, | the same HTTP request at the | | PERMANENT | PUT, PATCH, | the same HTTP request at the |
| REDIRECT | DELETE | location identified. The client | | REDIRECT | DELETE | location identified. The client |
| | | SHOULD use the location provided | | | | SHOULD use the location provided |
| | | in the response as the permanent | | | | in the response as the permanent |
| | | reference to the resource | | | | reference to the resource |
| | | [I-D.reschke-http-status-308]. | | | | [RFC7238]. |
| 400 BAD | GET, POST, | Request is unparseable, | | 400 BAD | GET, POST, | Request is unparseable, |
| REQUEST | PUT, PATCH, | syntactically incorrect, or | | REQUEST | PUT, PATCH, | syntactically incorrect, or |
| | DELETE | violates schema | | | DELETE | violates schema |
| 401 | GET, POST, | Authorization failure | | 401 | GET, POST, | Authorization failure |
| UNAUTHORIZED | PUT, PATCH, | | | UNAUTHORIZED | PUT, PATCH, | |
| | DELETE | | | | DELETE | |
| 403 | GET, POST, | Server does not support requested | | 403 | GET, POST, | Server does not support requested |
| FORBIDDEN | PUT, PATCH, | operation | | FORBIDDEN | PUT, PATCH, | operation |
| | DELETE | | | | DELETE | |
| 404 NOT | GET, PUT, | Specified resource (e.g., User) or | | 404 NOT | GET, PUT, | Specified resource (e.g., User) or |
skipping to change at page 66, line 5 skipping to change at page 65, line 25
"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:
ETag: W/"e180ee84f0671b1" https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1"
{ {
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646", "id":"2819c223-7f76-453a-919d-413861904646",
"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":
"version":"W\/\"e180ee84f0671b1\"" "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
}, "version":"W\/\"e180ee84f0671b1\""
"name":{ },
"formatted":"Ms. Barbara J Jensen III", "name":{
"familyName":"Jensen", "formatted":"Ms. Barbara J Jensen III",
"givenName":"Barbara" "familyName":"Jensen",
}, "givenName":"Barbara"
"userName":"bjensen" },
} "userName":"bjensen"
}
With the returned ETag, clients MAY choose to retrieve the resource With the returned ETag, clients MAY choose to retrieve the resource
only if the resource has been modified. only if the resource has been modified.
Conditional retrieval example using If-None-Match Section 3.2 Conditional retrieval example using If-None-Match Section 3.2
[RFC7233] header: [RFC7233] header:
GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName
Host: example.com Host: example.com
Accept: application/scim+json Accept: application/scim+json
skipping to change at page 69, line 20 skipping to change at page 68, line 34
thus subject to the security considerations of HTTP Section 9 thus subject to the security considerations of HTTP Section 9
[RFC7230] and its related specifications. [RFC7230] and its related specifications.
SCIM resources (e.g., Users and Groups) can contain sensitive SCIM resources (e.g., Users and Groups) can contain sensitive
information. Therefore, SCIM clients and service providers MUST information. Therefore, SCIM clients and service providers MUST
implement TLS. Which version(s) ought to be implemented will vary implement TLS. Which version(s) ought to be implemented will vary
over time, and depend on the widespread deployment and known security over time, and depend on the widespread deployment and known security
vulnerabilities at the time of implementation. At the time of this vulnerabilities at the time of implementation. At the time of this
writing, TLS version 1.2 [RFC5246] is the most recent version, but writing, TLS version 1.2 [RFC5246] is the most recent version, but
has very limited actual deployment, and might not be readily has very limited actual deployment, and might not be readily
available in implementation toolkits. TLS version 1.0 [RFC2246] is available in implementation toolkits. TLS version 1.0 [RFC5246] is
the most widely deployed version, and will give the broadest the most widely deployed version, and will give the broadest
interoperability. interoperability.
6.2. Disclosure of Sensitive Information in URIs 6.2. Disclosure of Sensitive Information in URIs
As mentioned in ,Section 9.4 [RFC7231], SCIM clients requesting As mentioned in ,Section 9.4 [RFC7231], SCIM clients requesting
information using query filters using HTTP GET SHOULD give information using query filters using HTTP GET SHOULD give
consideration to the information content of the filters and whether consideration to the information content of the filters and whether
their exposure in a URI would represent a breach of security or their exposure in a URI would represent a breach of security or
confidentiality through leakage in a web browsers or server logs. confidentiality through leakage in a web browsers or server logs.
skipping to change at page 70, line 5 skipping to change at page 69, line 11
privacy laws. In these situations to ensure maximum security and privacy laws. In these situations to ensure maximum security and
confidentiality, clients SHOULD query using HTTP POST (see confidentiality, clients SHOULD query using HTTP POST (see
Section 3.2.3 ). Section 3.2.3 ).
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:ietf:params: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":
"error":"confidential_restricted" "Query filter involving 'name' is restricted or confidential",
} "error":"confidential_restricted"
] }
} ]
}
6.3. Anonymous Requests 6.3. Anonymous Requests
If a SCIM service provider accepts anonymous requests such as SCIM If a SCIM service provider accepts anonymous requests such as SCIM
resource creation requests (via HTTP POST), appropriate security resource creation requests (via HTTP POST), appropriate security
measures should be put in place to prevent or limit exposure to measures should be put in place to prevent or limit exposure to
attacks. The following counter-measures MAY be used: attacks. The following counter-measures MAY be used:
o Try to authenticate web UI components that forumulate the SCIM o Try to authenticate web UI components that forumulate the SCIM
creation request. While the end-user MAY be anonymous, the web creation request. While the end-user MAY be anonymous, the web
skipping to change at page 73, line 51 skipping to change at page 73, line 12
Table 9: 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-08
(work in progress), March 2014. (work in progress), October 2014.
[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-10 (work in Schema", draft-ietf-scim-core-schema-12 (work in
progress), September 2014. progress), October 2014.
[IANA.Language]
Internet Assigned Numbers Authority (IANA), "Language
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",
RFC 2246, January 1999.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3454] Hoffman, P. and M. Blanchet, "Preparation of
Internationalized Strings ("stringprep")", RFC 3454,
December 2002.
[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.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
skipping to change at page 75, line 20 skipping to change at page 74, line 13
June 2014. June 2014.
[RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Authentication", RFC 7235, June 2014. (HTTP/1.1): Authentication", RFC 7235, June 2014.
8.2. Informative References 8.2. Informative References
[I-D.ietf-precis-framework] [I-D.ietf-precis-framework]
Saint-Andre, P. and M. Blanchet, "PRECIS Framework: Saint-Andre, P. and M. Blanchet, "PRECIS Framework:
Preparation and Comparison of Internationalized Strings in Preparation and Comparison of Internationalized Strings in
Application Protocols", draft-ietf-precis-framework-17 Application Protocols", draft-ietf-precis-framework-18
(work in progress), May 2014. (work in progress), September 2014.
[I-D.reschke-http-status-308]
Reschke, J., "The Hypertext Transfer Protocol (HTTP)
Status Code 308 (Permanent Redirect)", draft-reschke-http-
status-308-07 (work in progress), March 2012.
[OpenSearch] [OpenSearch]
Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . Clinton, D., "OpenSearch Protocol 1.1, Draft 5", .
[Order-Operations] [Order-Operations]
Wikipedia, "Order of Operations: Programming Languages", . Wikipedia, "Order of Operations: Programming Languages", .
[RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
Languages", BCP 18, RFC 2277, January 1998.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
6749, October 2012. 6749, October 2012.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, October 2012. Framework: Bearer Token Usage", RFC 6750, October 2012.
[RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819, Threat Model and Security Considerations", RFC 6819,
January 2013. January 2013.
[RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation
(JSON) Patch", RFC 6902, April 2013. (JSON) Patch", RFC 6902, April 2013.
[RFC7238] Reschke, J., "The Hypertext Transfer Protocol Status Code
308 (Permanent Redirect)", RFC 7238, June 2014.
Appendix A. Contributors Appendix A. Contributors
Samuel Erdtman (samuel@erdtman.se) Samuel Erdtman (samuel@erdtman.se)
Patrick Harding (pharding@pingidentity.com) Patrick Harding (pharding@pingidentity.com)
Appendix B. Acknowledgments Appendix B. Acknowledgments
The editors would like to acknowledge the contribution and work of The editors would like to acknowledge the contribution and work of
the past draft editors: the past draft editors:
skipping to change at page 79, line 19 skipping to change at page 78, line 4
Draft 11 - PH - Revisions as follows Draft 11 - PH - Revisions as follows
Made mutability processing rules for CREATE more editorially Made mutability processing rules for CREATE more editorially
obvious obvious
Added clarfications and security considerations for Anonymous Added clarfications and security considerations for Anonymous
operations operations
Added clarifications to "/Me" for POST requests Added clarifications to "/Me" for POST requests
Clarified use of bulkids with multiple requests Clarified use of bulkids with multiple requests
Corrected JSON parsing issue by adding "Operations" attribute to Corrected JSON parsing issue by adding "Operations" attribute to
PATCH operation PATCH operation
Draft 12 - PH - Editorial NITs
Fix line lengths in artwork to be 72 chars or less
Remove unused references
Fix normative terms per RFC2119
Updated reference to draft-reschke-http-status-308 to RFC7238
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. 58 change blocks. 
452 lines changed or deleted 484 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/