draft-ietf-scim-api-09.txt   draft-ietf-scim-api-10.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 13, 2015 SailPoint Expires: March 5, 2015 SailPoint
M. Ansari M. Ansari
Cisco Cisco
E. Wahlstroem E. Wahlstroem
Nexus Technology Nexus Technology
C. Mortimore C. Mortimore
Salesforce Salesforce
August 12, 2014 September 1, 2014
System for Cross-Domain Identity Management:Protocol System for Cross-Domain Identity Management 0;,Protocol
draft-ietf-scim-api-09 draft-ietf-scim-api-10
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 an HTTP based protocol that makes managing identities in multi-
applications and services easier using HTTP Protocol. Examples domain scenarios easier to support through a standardized services.
include but are not limited to enterprise to cloud service providers, Examples include but are not limited to enterprise to cloud service
and inter-cloud based scenarios. The specification suite seeks to providers, and inter-cloud based scenarios. The specification suite
build upon experience with existing schemas and deployments, placing seeks to build upon experience with existing schemas and deployments,
specific emphasis on simplicity of development and integration, while placing specific emphasis on simplicity of development and
applying existing authentication, authorization, and privacy models. integration, while applying existing authentication, authorization,
It's intent is to reduce the cost and complexity of user management and privacy models. SCIM's intent is to reduce the cost and
operations by providing a common user schema and extension model, as complexity of user management operations by providing a common user
well as binding documents to provide patterns for exchanging this schema and extension model and a service protocol defined by this
schema using standard protocols. In essence, make it fast, cheap, document.
and easy to move users in to, out of, and around the cloud.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 13, 2015. This Internet-Draft will expire on March 5, 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 27 skipping to change at page 2, line 27
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3
1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3
1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4
2. Authentication and Authorization . . . . . . . . . . . . . . 4 2. Authentication and Authorization . . . . . . . . . . . . . . 4
3. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 4 3. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 5
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 . . . . . . . . . . . . . . . . . . . 10
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 . . . . . . . . . . . . . . . . . . . 39 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 39
3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 40 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 40
3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 55 3.5.1. Circular Reference Processing . . . . . . . . . . . . 42
3.7. Additional Operation Response Parameters . . . . . . . . 56 3.5.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 46
3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 57 3.5.3. Response and Error Handling . . . . . . . . . . . . . 49
3.5.4. Maximum Operations . . . . . . . . . . . . . . . . . 55
3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 56
3.7. Additional Operation Response Parameters . . . . . . . . 57
3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 58
3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 58 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 58
3.10. HTTP Status and Error Response Handling . . . . . . . . . 58 3.10. HTTP Status and Error Response Handling . . . . . . . . . 59
3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 62 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 63
3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 62 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 63
4. Preparation and Comparison of Internationalized Strings . . . 64 4. Preparation and Comparison of Internationalized Strings . . . 65
5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 64 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 65
5.1. Associating Clients to Tenants . . . . . . . . . . . . . 65 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 66
5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 66 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 66
6. Security Considerations . . . . . . . . . . . . . . . . . . . 66 6. Security Considerations . . . . . . . . . . . . . . . . . . . 67
6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 66 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 67
6.2. Disclosure of Sensitive Information in URIs . . . . . . . 66 6.2. Disclosure of Sensitive Information in URIs . . . . . . . 67
6.3. HTTP Considerations . . . . . . . . . . . . . . . . . . . 67 6.3. HTTP Considerations . . . . . . . . . . . . . . . . . . . 68
6.4. Secure Storage and Handling of Sensitive Data . . . . . . 67 6.4. Secure Storage and Handling of Sensitive Data . . . . . . 68
6.5. Case Insensitive Comparision & International Languages . 68 6.5. Case Insensitive Comparision & International Languages . 69
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69
7.1. Media Type Registration . . . . . . . . . . . . . . . . . 68 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 69
7.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 69 7.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 70
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 70 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 71
8.1. Normative References . . . . . . . . . . . . . . . . . . 70 8.1. Normative References . . . . . . . . . . . . . . . . . . 71
8.2. Informative References . . . . . . . . . . . . . . . . . 71 8.2. Informative References . . . . . . . . . . . . . . . . . 72
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 72 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 73
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 72 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 73
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 72 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 73
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 76
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.
1.1. Intended Audience 1.1. Intended Audience
This document is intended as a guide to SCIM API usage for both SCIM This document is intended as a guide to SCIM protocol usage for both
HTTP service providers and HTTP clients that may provision SCIM HTTP service providers and HTTP clients who may provision
information to service providers or retrieve information from them. information to service providers or retrieve information from them.
1.2. Notational Conventions 1.2. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. These document are to be interpreted as described in [RFC2119]. These
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 Implementers MUST percent encode URLs as described in Section 2.1 of
[RFC3986]. [RFC3986].
1.3. Definitions 1.3. Definitions
Base URI: The SCIM HTTP protocol is described in terms of a path Base URI
relative to a Base URI. The Base URI MUST NOT contain a query The SCIM HTTP protocol is described in terms of a path relative to
string as clients may append additional path information and query a Base URI. The Base URI MUST NOT contain a query string as
parameters as part of forming the request. Example: clients may append additional path information and query
parameters as part of forming the request. The base URI most
often is a URL which most often consists of the "https" protocol
scheme, a domain name and some initial path [RFC3986]. Example:
"https://example.com/scim/" "https://example.com/scim/"
For readability, all examples in this document are expressed For readability, all examples in this document are expressed
assuming the SCIM service root and the server root are the same. assuming the SCIM service root and the server root are the same
It is expected that SCIM servers may be deployed using any URI (no path pre-fix). It is expected that SCIM servers may be
prefix. For example, a SCIM server might be have a prefix of deployed using any URI path prefix. For example, a SCIM server
"https://example.com/", or "https://example.com/scim/ might be have a prefix of "https://example.com/", or
tenancypath/". Additionally client may also apply a version "https://example.com/scim/tenancypath/". Additionally client may
number to the server root prefix (see Section 3.11 ). also apply a version number to the server root prefix (see
Section 3.11 ).
2. Authentication and Authorization 2. Authentication and Authorization
Because SCIM builds on the HTTP protocol, it does not define a scheme Because SCIM builds on the HTTP protocol, it does not itself define a
for authentication and authorization. SCIM depends on standard HTTP scheme for authentication and authorization. SCIM depends on
authentication schemes. Implementers SHOULD support existing standard HTTP authentication schemes. Implementers SHOULD support
authentication/authorization schemes. In particular, OAuth2 existing authentication/authorization schemes. In particular, OAuth2
[RFC6750] is RECOMMENDED. Appropriate security considerations of the [RFC6750] is RECOMMENDED. Appropriate security considerations of the
selected authentication and authorization schemes SHOULD be taken. selected authentication and authorization schemes SHOULD be taken.
Because this protocol uses HTTP response status codes as the primary Because this protocol uses HTTP response status codes as the primary
means of reporting the result of a request, servers are advised to means of reporting the result of a request, servers are advised to
respond to unauthorized or unauthenticated requests using the 401 respond to unauthorized or unauthenticated requests using the 401
response code in accordance with Section 3.1 of [RFC7235]. response code in accordance with Section 3.1 of [RFC7235].
All examples show an OAuth2 bearer token [RFC6750] (though it is not All examples show an OAuth2 bearer token [RFC6750] (though it is not
required) ; e.g., required); e.g.,
GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1
Host: example.com Host: example.com
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
The context of the request (i.e. the user for whom data is being When processing requests, the service provider SHOULD consider the
requested) MUST be inferred by service providers. subject performing the request and whether the action is appropriate
given the subject and the resource affected by the request. The
subject performing the request is usually determined from the
"Authorization" header present in the request.
3. SCIM Protocol 3. SCIM Protocol
The SCIM protocol specifies well known endpoints and HTTP methods for The SCIM protocol specifies well-known endpoints and HTTP methods for
managing resources defined in the core schema; i.e., "User" and managing resources defined in the core schema; i.e., "User" and
"Group" resources correspond to "/Users" and "/Groups" respectively. "Group" resources correspond to "/Users" and "/Groups" respectively.
Service providers that support extended resources SHOULD define Service providers that support extended resources SHOULD define
resource endpoints using the established convention; pluralize the resource endpoints using the convention of pluralizing the resource
resource name defined in the extended schema by appending an 's'. name defined in the extended schema by appending an 's'. Given there
Given there are cases where resource pluralization is ambiguous; are cases where resource pluralization is ambiguous; e.g., a resource
e.g., a resource named "Person" is legitimately "Persons" and named "Person" is legitimately "Persons" and "People". Clients
"People" clients SHOULD discover resource endpoints via the SHOULD discover resource endpoints via the "/ResourceTypes" endpoint.
"/ResourceTypes" endpoint.
GET Retrieves one or more complete or partial resources. GET
Retrieves one or more complete or partial resources.
POST Depending on the endpoint, creates new resources, create a POST
search request, or may be used to bulk modify resources. Depending on the endpoint, creates new resources, create a search
request, or may be used to bulk modify resources.
PUT Modifies a resource by replacing existing attributes with a PUT
Modifies a resource by replacing existing attributes with a
specified set of replacement attributes (replace). PUT MUST NOT specified set of replacement attributes (replace). PUT MUST NOT
be used to create new resources. be used to create new resources.
PATCH Modifies a resource with a set of client specified changes PATCH
Modifies a resource with a set of client specified changes
(partial update). (partial update).
DELETE Deletes a resource. DELETE
Deletes a resource.
Resource Endpoint Operations Description Resource Endpoint Operations Description
-------- ---------------- ---------------------- -------------------- -------- ---------------- ---------------------- --------------------
User /Users GET (Section 3.2.1), Retrieve, Add, User /Users GET (Section 3.2.1), Retrieve, Add,
POST (Section 3.1), Modify Users POST (Section 3.1), Modify Users
PUT (Section 3.3.1), PUT (Section 3.3.1),
PATCH (Section 3.3.2), PATCH (Section 3.3.2),
DELETE (Section 3.4) DELETE (Section 3.4)
Group /Groups GET (Section 3.2.1), Retrieve, Add, Group /Groups GET (Section 3.2.1), Retrieve, Add,
POST (Section 3.1), Modify Groups POST (Section 3.1), Modify Groups
skipping to change at page 34, line 31 skipping to change at page 34, line 31
"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
("..."): ("..."):
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"
skipping to change at page 35, line 36 skipping to change at page 35, line 36
"$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 o If the "path" parameter is omitted, the target is assumed to be
the resoruce itself. In this case, the "value" attribute SHALL the resource itself. In this case, the "value" attribute SHALL
contain a list of one or more attributes that are to be replaced. contain a list of one or more attributes that are to be replaced.
o If the target location is a single-value attribute, the attributes o If the target location is a single-value attribute, the attributes
value is replaced. value is replaced.
o If the target location is a multi-valued attribute and no filter o If the target location is a multi-valued attribute and no filter
is specified, the attribute and all values are replaced. is specified, the attribute and all values are replaced.
o If the target location specifies a complex attribute, a set of o If the target location specifies a complex attribute, a set of
sub-attributes SHALL be specified in the "value" parameter which sub-attributes SHALL be specified in the "value" parameter which
skipping to change at page 40, line 50 skipping to change at page 40, line 50
"urn:ietf:params:scim:api:messages:2.0:BulkRequest". Bulk responses "urn:ietf:params:scim:api:messages:2.0:BulkRequest". Bulk responses
are identified using the following URI: are identified using the following URI:
"urn:ietf:params:scim:api:messages:2.0:BulkResponse". Bulk requests "urn:ietf:params:scim:api:messages:2.0:BulkResponse". Bulk requests
and bulk responses share many attributes. Unless otherwise and bulk responses share many attributes. Unless otherwise
specified, each attribute below is present in both bulk requests and specified, each attribute below is present in both bulk requests and
bulk responses. bulk responses.
The following Singular Attribute is defined in addition to the common The following Singular Attribute is defined in addition to the common
attributes defined in SCIM core schema. attributes defined in SCIM core schema.
failOnErrors An Integer specifying the number of errors that the failOnErrors
service provider will accept before the operation is terminated An Integer specifying the number of errors that the service
and an error response is returned. OPTIONAL in a request. Not provider will accept before the operation is terminated and an
valid in a response. error response is returned. OPTIONAL in a request. Not valid in
a response.
The following Complex Multi-valued Attribute is defined in addition The following Complex Multi-valued Attribute is defined in addition
to the common attributes defined in core schema. to the common attributes defined in core schema.
Operations Defines operations within a bulk job. Each operation Operations
corresponds to a single HTTP request against a resource endpoint. Defines operations within a bulk job. Each operation corresponds
REQUIRED. to a single HTTP request against a resource endpoint. REQUIRED.
Operations has the following sub-attributes:
method The HTTP method of the current operation. Possible values method The HTTP method of the current operation. Possible values
are POST, PUT, PATCH or DELETE. REQUIRED. are POST, PUT, PATCH or DELETE. REQUIRED.
bulkId The transient identifier of a newly created resource, bulkId The transient identifier of a newly created resource,
unique within a bulk request and created by the client. The unique within a bulk request and created by the client. The
bulkId serves as a surrogate resource id enabling clients to bulkId serves as a surrogate resource id enabling clients to
uniquely identify newly created resources in the Response and uniquely identify newly created resources in the Response and
cross reference new resources in and across operations within a cross reference new resources in and across operations within a
bulk request. REQUIRED when method is POST. bulk request. REQUIRED when method is POST.
skipping to change at page 42, line 17 skipping to change at page 42, line 17
returned. returned.
The service provider MUST continue performing as many changes as The service provider MUST continue performing as many changes as
possible and disregard partial failures. The client MAY override possible and disregard partial failures. The client MAY override
this behavior by specifying a value for the "failOnErrors" attribute. this behavior by specifying a value for the "failOnErrors" attribute.
The failOnErrors attribute defines the number of errors that the The failOnErrors attribute defines the number of errors that the
service provider should accept before failing the remaining service provider should accept before failing the remaining
operations returning the response. operations returning the response.
To be able to reference a newly created resource the attribute bulkId To be able to reference a newly created resource the attribute bulkId
MUST be specified when creating new resources. The bulkId is defined MUST be specified when creating new resources. The "bulkId" is
by the client as a surrogate identifier in a POST operation. The defined by the client as a surrogate identifier in a POST operation
service provider MUST return the same bulkId together with the newly (see Section 3.5.2). The service provider MUST return the same
created resource. The bulkId can then be used by the client to map "bulkId" together with the newly created resource. The "bulkId" can
the service provider id with the bulkId of the created resource. then be used by the client to map the service provider id with the
"bulkId" of the created resource.
A SCIM service provider MAY elect to optimize a sequence operations A SCIM service provider MAY elect to optimize a sequence operations
received (e.g. to improve processing performance). When doing so, received (e.g. to improve processing performance). When doing so,
the service provider MUST ensure the clients intent is preserved and the service provider MUST ensure the clients intent is preserved and
the same stateful result is achieved as for non-optimized processing. the same stateful result is achieved as for non-optimized processing.
For example, before a "User" can be added to a "Group", they must For example, before a "User" can be added to a "Group", they must
first be created. Processing these requests out of order, might first be created. Processing these requests out of order, might
result in a failure to add the new "User" to the "Group". result in a failure to add the new "User" to the "Group".
3.5.1. Circular Reference Processing
The service provider MUST try to resolve circular cross references
between resources in a single bulk job but MAY stop after a failed
attempt and instead return the status code 409 Conflict. The
following example exhibits the potential conflict.
POST /v2/Bulk
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"Operations": [
{
"method": "POST",
"path": "/Groups",
"bulkId": "qwerty",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group A",
"members": [
{
"type": "Group",
"value": "bulkId:ytrewq"
}
]
}
},
{
"method": "POST",
"path": "/Groups",
"bulkId": "ytrewq",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group B",
"members": [
{
"type": "Group",
"value": "bulkId:qwerty"
}
]
}
}
]
}
If the service provider resolved the above circular references the
following is returned from a subsequent GET request.
GET /v2/Groups?filter=displayName sw 'Group'
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 2,
"Resources": [
{
"id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group A",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T18:29:51.135Z",
"location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"version": "W\/\"mvwNGaxB5SDq074p\""
},
"members": [
{
"value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"type": "Group"
}
]
},
{
"id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group B",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:50.873Z",
"lastModified": "2011-08-01T18:29:50.873Z",
"location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"version": "W\/\"wGB85s2QJMjiNnuI\""
},
"members": [
{
"value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"type": "Group"
}
]
}
]
}
3.5.2. BulkdId Temporary Identifiers
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 order to add the new "User" to the "Group" the client
must use the surrogate id attribute, "bulkId", to reference the User.
The "bulkId" attribute value must be pre-pended with the literal
"bulkId:"; e.g., if the bulkId is 'qwerty', the value is
"bulkId:qwerty". The service provider MUST replace the string
"bulkId:qwerty" with the permanent resource id once created.
The following example creates a User with the "userName" 'Alice' and
a "Group" with the "displayName" 'Tour Guides' with Alice as a
member.
POST /v2/Bulk
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"Operations": [
{
"method": "POST",
"path": "/Users",
"bulkId": "qwerty",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "Alice"
}
},
{
"method": "POST",
"path": "/Groups",
"bulkId": "ytrewq",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Tour Guides",
"members": [
{
"type": "User",
"value": "bulkId:qwerty"
}
]
}
}
]
}
The service provider returns the following response:
A subsequent GET request for the 'Tour Guides' Group ('e9e30dba-f08f-
4109-8486-d5c6a331660a') returns the following:
HTTP/1.1 200 OK
Content-Type: application/scim+json
Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
ETag: W/"lha5bbazU3fNvfe5"
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
"displayName": "Tour Guides",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T20:31:02.315Z",
"location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"version": "W\/\"lha5bbazU3fNvfe5\""
},
"members": [
{
"value": "92b725cd-9465-4e7d-8c16-01f8e146b87a",
"$ref": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"type": "User"
}
]
}
Extensions that include references to other resources MUST be handled
in the same way by the service provider. The following example uses
the bulkId attribute within the enterprise extension managerId
attribute.
POST /v2/Bulk
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"Operations": [
{
"method": "POST",
"path": "/Users",
"bulkId": "qwerty",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "Alice"
}
},
{
"method": "POST",
"path": "/Users",
"bulkId": "ytrewq",
"data": {
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"userName": "Bob",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "11250",
"manager": {
"managerId": "batchId:qwerty",
"displayName": "Alice"
}
}
}
}
]
}
3.5.3. Response and Error Handling
The service provider response MUST include the result of all The service provider response MUST include the result of all
processed operations. A "location" attribute that includes the processed operations. A "location" attribute that includes the
resource's endpoint MUST be returned for all operations excluding resource's endpoint MUST be returned for all operations excluding
failed POSTs. The status attribute includes information about the failed POSTs. The status attribute includes information about the
success or failure of one operation within the bulk job. The success or failure of one operation within the bulk job. The
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.
skipping to change at page 43, line 14 skipping to change at page 50, line 23
"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":"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
skipping to change at page 46, line 25 skipping to change at page 53, line 25
"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":"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:ietf:params:scim:api:messages:2.0:BulkResponse"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [ "Operations": [
skipping to change at page 47, line 31 skipping to change at page 55, line 4
"method": "DELETE", "method": "DELETE",
"status": "404", "status": "404",
"response":{ "response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Resource does not exist.", "detail":"Resource does not exist.",
"status":"404" "status":"404"
} }
} }
] ]
} }
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
order to add the new User to the Group the client must use the
surrogate id attribute, bulkId, to reference the User. The bulkId
attribute value must be pre-pended with the literal "bulkId:"; e.g.,
if the bulkId is 'qwerty' the value is "bulkId:qwerty". The service
provider MUST replace the string "bulkId:qwerty" with the permanent
resource id once created.
The following example creates a User with the userName 'Alice' and a
Group with the displayName 'Tour Guides' with Alice as a member.
POST /v2/Bulk
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"Operations": [
{
"method": "POST",
"path": "/Users",
"bulkId": "qwerty",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "Alice"
}
},
{
"method": "POST",
"path": "/Groups",
"bulkId": "ytrewq",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Tour Guides",
"members": [
{
"type": "User",
"value": "bulkId:qwerty"
}
]
}
}
]
}
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": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST", "method": "POST",
"bulkId": "qwerty", "bulkId": "qwerty",
skipping to change at page 49, line 28 skipping to change at page 55, line 27
{ {
"location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"method": "POST", "method": "POST",
"bulkId": "ytrewq", "bulkId": "ytrewq",
"version": "W\/\"lha5bbazU3fNvfe5\"", "version": "W\/\"lha5bbazU3fNvfe5\"",
"status": "201" "status": "201"
} }
] ]
} }
A subsequent request for the 'Tour Guides' Group ('e9e30dba-f08f- 3.5.4. Maximum Operations
4109-8486-d5c6a331660a') returns the following:
GET /v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
HTTP/1.1 200 OK
Content-Type: application/scim+json
Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
ETag: W/"lha5bbazU3fNvfe5"
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
"displayName": "Tour Guides",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T20:31:02.315Z",
"location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"version": "W\/\"lha5bbazU3fNvfe5\""
},
"members": [
{
"value": "92b725cd-9465-4e7d-8c16-01f8e146b87a",
"$ref": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"type": "User"
}
]
}
Extensions that include references to other resources MUST be handled
in the same way by the service provider. The following example uses
the bulkId attribute within the enterprise extension managerId
attribute.
POST /v2/Bulk
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"Operations": [
{
"method": "POST",
"path": "/Users",
"bulkId": "qwerty",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "Alice"
}
},
{
"method": "POST",
"path": "/Users",
"bulkId": "ytrewq",
"data": {
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"userName": "Bob",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "11250",
"manager": {
"managerId": "batchId:qwerty",
"displayName": "Alice"
}
}
}
}
]
}
The service provider MUST try to resolve circular cross references
between resources in a single bulk job but MAY stop after a failed
attempt and instead return the status code 409 Conflict. The
following example exhibits the potential conflict.
POST /v2/Bulk
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"Operations": [
{
"method": "POST",
"path": "/Groups",
"bulkId": "qwerty",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group A",
"members": [
{
"type": "Group",
"value": "bulkId:ytrewq"
}
]
}
},
{
"method": "POST",
"path": "/Groups",
"bulkId": "ytrewq",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group B",
"members": [
{
"type": "Group",
"value": "bulkId:qwerty"
}
]
}
}
]
}
If the service provider resolved the above circular references the
following is returned from a subsequent GET request.
GET /v2/Groups?filter=displayName sw 'Group'
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 2,
"Resources": [
{
"id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group A",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T18:29:51.135Z",
"location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"version": "W\/\"mvwNGaxB5SDq074p\""
},
"members": [
{
"value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"type": "Group"
}
]
},
{
"id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Group B",
"meta": {
"resourceType": "Group",
"created": "2011-08-01T18:29:50.873Z",
"lastModified": "2011-08-01T18:29:50.873Z",
"location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"version": "W\/\"wGB85s2QJMjiNnuI\""
},
"members": [
{
"value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"type": "Group"
}
]
}
]
}
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. If maximum payload size a client may send in a single request. If
either limits are exceeded the service provider MUST return the HTTP either limits are exceeded the service provider MUST return the HTTP
response code 413 Request Entity Too Large. The returned response response code 413 Request Entity Too Large. The returned response
MUST specify the limit exceeded in the body of the error response. MUST specify the limit exceeded in the body of the error response.
The following example the client sent a request exceeding the service The following example the client sent a request exceeding the service
provider's max payload size of 1 megabyte. provider's max payload size of 1 megabyte.
POST /v2/Bulk POST /v2/Bulk
skipping to change at page 70, line 37 skipping to change at page 71, line 37
[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-08 (work in Schema", draft-ietf-scim-core-schema-09 (work in
progress), August 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",
skipping to change at page 75, line 24 skipping to change at page 76, line 24
Draft 09 - PH - Revisions as follows Draft 09 - PH - Revisions as follows
- Aligned API with new URN namespace per RFC3553 and IETF90 - Aligned API with new URN namespace per RFC3553 and IETF90
meeting meeting
- Clarified URN usage within patch (what schema urn applies) - Clarified URN usage within patch (what schema urn applies)
- Made 'path' optional in PATCH for Add and Replace - Made 'path' optional in PATCH for Add and Replace
Draft 10 - PH - Revisions as follows
Restructuring of Bulk into sub-sections
General clarifications
Improved Base URI section
Authorization section clarifications
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. 38 change blocks. 
328 lines changed or deleted 358 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/