RFC 7644
System for Cross-domain Identity Management: Protocol
3.7. Bulk Operations
The SCIM bulk operation is an optional server feature that enables clients to send a potentially large collection of resource operations in a single request. Support for bulk requests can be discovered by querying the service provider configuration (see Section 4). The body of a bulk operation contains a set of HTTP resource operations using one of the HTTP methods supported by the API, i.e., POST, PUT, PATCH, or DELETE. Bulk requests are identified using the following schema URI: "urn:ietf:params:scim:api:messages:2.0:BulkRequest". Bulk responses are identified using the following URI: "urn:ietf:params:scim:api:messages:2.0:BulkResponse". Bulk requests and bulk responses share many attributes. Unless otherwise specified, each attribute below is present in both bulk requests and bulk responses. The following singular attribute is defined, in addition to the common attributes defined in [RFC7643]. failOnErrors An integer specifying the number of errors that the service provider will accept before the operation is terminated and an error response is returned. OPTIONAL in a request. Not valid in a response. The following complex multi-valued attribute is defined, in addition to the common attributes defined in [RFC7643]. Operations Defines operations within a bulk job. Each operation corresponds to a single HTTP request against a resource endpoint. REQUIRED. The Operations attribute has the following sub-attributes: method The HTTP method of the current operation. Possible values are "POST", "PUT", "PATCH", or "DELETE". REQUIRED. bulkId The transient identifier of a newly created resource, unique within a bulk request and created by the client. The bulkId serves as a surrogate resource id enabling clients to uniquely identify newly created resources in the response and cross-reference new resources in and across operations within a bulk request. REQUIRED when "method" is "POST". version The current resource version. Version MAY be used if the service provider supports entity-tags (ETags) (Section 2.3 of [RFC7232]) and "method" is "PUT", "PATCH", or "DELETE".
path The resource's relative path to the SCIM service provider's
root. If "method" is "POST", the value must specify a resource
type endpoint, e.g., /Users or /Groups, whereas all other
"method" values must specify the path to a specific resource,
e.g., /Users/2819c223-7f76-453a-919d-413861904646. REQUIRED in
a request.
data The resource data as it would appear for a single SCIM POST,
PUT, or PATCH operation. REQUIRED in a request when "method"
is "POST", "PUT", or "PATCH".
location The resource endpoint URL. REQUIRED in a response,
except in the event of a POST failure.
response The HTTP response body for the specified request
operation. When indicating a response with an HTTP status
other than a 200-series response, the response body MUST be
included. For normal completion, the server MAY elect to omit
the response body.
status The HTTP response status code for the requested operation.
When indicating an error, the "response" attribute MUST contain
the detail error response as per Section 3.12.
If a bulk job is processed successfully, HTTP response code 200 OK
MUST be returned; otherwise, an appropriate HTTP error code MUST be
returned.
The service provider MUST continue performing as many changes as
possible and disregard partial failures. The client MAY override
this behavior by specifying a value for the "failOnErrors" attribute.
The "failOnErrors" attribute defines the number of errors that the
service provider should accept before failing the remaining
operations returning the response.
To be able to reference a newly created resource, the bulkId
attribute MAY be specified when creating new resources. The "bulkId"
is defined by the client as a surrogate identifier in a POST
operation (see Section 3.7.2). The service provider MUST return the
same "bulkId" together with the newly created resource. The "bulkId"
can 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 the sequence of
operations received (e.g., to improve processing performance). When
doing so, the service provider MUST ensure that the client's intent
is preserved and the same stateful result is achieved as for
non-optimized processing. For example, before a "User" can be added to a "Group", they must first be created. Processing these requests out of order might result in a failure to add the new "User" to the "Group".3.7.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 HTTP 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.7.2. "bulkId" Temporary Identifiers
A SCIM client can, within one bulk operation, create a new "User",
create 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 prepended 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.
To create multiple distinct requests, each with their own "bulkId",
the SCIM client specifies different "bulkId" values for each separate
request.
The following example creates a User with the "userName" 'Alice' and
a "Group" with "displayName", with a value of "Tour Guides" with
Alice as a member. Notice that each operation has its own "bulkId"
value. However, the second operation (whose "bulkId" is "ytrewq")
refers to the "bulkId" of "qwerty" in order to add Alice to the new
'Tour Guides' group.
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
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [
{
"location":
"https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST",
"bulkId": "qwerty",
"version": "W\/\"4weymrEsh5O6cAEK\"",
"status": {
"code": "201"
}
},
{
"location":
"https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"method": "POST",
"bulkId": "ytrewq",
"version": "W\/\"lha5bbazU3fNvfe5\"",
"status": {
"code": "201"
}
}
]
}
In the above example, the "Alice" User resource has an "id" of
"92b725cd-9465-4e7d-8c16-01f8e146b87a" and the 'Tour Guides' Group
has an "id" of "e9e30dba-f08f-4109-8486-d5c6a331660a".
A subsequent GET request for the 'Tour Guides' Group (with an "id" of
"e9e30dba-f08f-4109-8486-d5c6a331660a") returns the following, with
Alice's "id" as the value for the member in the Group 'Tour Guides':
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": {
"value": "bulkId:qwerty"
}
}
}
}
]
}
3.7.3. Response and Error Handling
The service provider response MUST include the result of all processed operations. A "location" attribute that includes the resource's endpoint MUST be returned for all operations except for failed POST operations (which have no location). The status attribute includes information about the success or failure of one operation within the bulk job. The status attribute MUST include the code attribute that holds the HTTP response code that would have been returned if a single HTTP request would have been used. If an error occurred, the status MUST also include the description attribute containing a human-readable explanation of the error. "status": "201" The following is an example of a status in a failed operation. "status": "400", "response":{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "scimType":"invalidSyntax" "detail": "Request is unparsable, syntactically incorrect, or violates schema.", "status":"400" }
The following example shows how to add, update, and remove a user.
The "failOnErrors" attribute is set to '1', indicating that the
service provider will stop processing and return results after one
error. The POST operation's bulkId value is set to 'qwerty',
enabling the client to match the new User with the returned
resource "id" of
"92b725cd-9465-4e7d-8c16-01f8e146b87a".
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"],
"failOnErrors":1,
"Operations":[
{
"method":"POST",
"path":"/Users",
"bulkId":"qwerty",
"data":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:User"],
"userName":"Alice"
}
},
{
"method":"PUT",
"path":"/Users/b7c14771-226c-4d05-8860-134711653041",
"version":"W\/\"3694e05e9dff591\"",
"data":{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"b7c14771-226c-4d05-8860-134711653041",
"userName":"Bob"
}
},
{
"method": "PATCH",
"path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"version": "W/\"edac3253e2c0ef2\"",
"data": {[
{
"op": "remove",
"path": "nickName"
},
{
"op": "add",
"path": "userName",
"value": "Dave"
}
]}
},
{
"method":"DELETE",
"path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"version":"W\/\"0ee8add0a938e1a\""
}
]
}
The service provider returns the following response:
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [
{
"location":
"https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST",
"bulkId": "qwerty",
"version": "W\/\"oY4m4wn58tkVjJxK\"",
"status": "201"
},
{
"location":
"https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT",
"version": "W\/\"huJj29dMNgu3WXPD\"",
"status": "200"
},
{
"location":
"https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH",
"version": "W\/\"huJj29dMNgu3WXPD\"",
"status": "200"
},
{
"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
attempting to create the User 'Alice'. The service provider stops
processing the bulk operation and immediately returns a response to
the client. The response contains the error and any successful
results prior to the error.
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [
{
"method": "POST",
"bulkId": "qwerty",
"status": "400",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax"
"detail":
"Request is unparsable, syntactically incorrect, or violates schema.",
"status":"400"
}
}
]
}
If the "failOnErrors" attribute is not specified or the service
provider has not reached the error limit defined by the client, the
service provider will continue to process all operations. The
following is an example in which all operations failed.
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [
{
"method": "POST",
"bulkId": "qwerty",
"status": "400",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidSyntax"
"detail":
"Request is unparsable, syntactically incorrect, or violates schema.",
"status":"400"
}
},
{
"location":
"https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT",
"status": "412",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":
"Failed to update. Resource changed on the server.",
"status":"412"
}
},
{
"location":
"https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH",
"status": "412",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":
"Failed to update. Resource changed on the server.",
"status":"412"
}
},
{
"location":
"https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE",
"status": "404",
"response":{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Resource does not exist.",
"status":"404"
}
}
]
}
3.7.4. Maximum Operations
The service provider MUST define the maximum number of operations and
maximum payload size a client may send in a single request. These
limits MAY be retrieved from the service provider configuration (see
'bulk' in Sections 5 and 8.5 of [RFC7643]). If either limit is
exceeded, the service provider MUST return HTTP response code 413
(Payload Too Large). The returned response MUST specify the limit
exceeded in the body of the error response.
In the following example, the client sent a request exceeding the
service provider's maximum payload size of 1 megabyte:
POST /v2/Bulk
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: 4294967296
...
The server sends the following error in response to the oversized
request:
HTTP/1.1 413 Payload Too Large
Content-Type: application/scim+json
{
"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],
"status": "413",
"detail":
"The size of the bulk operation exceeds the maxPayloadSize (1048576)."
}
3.8. Data Input/Output Formats
Servers MUST accept requests and be able to return JSON-structured responses using UTF-8 encoding [RFC3629]. UTF-8 SHALL be the default encoding format. Other media types MAY be supported by service providers but are beyond the scope of this specification. Clients using other encodings MUST specify the format in which the data is submitted via an HTTP "Content-Type" header as specified in Section 3.1.1.5 of [RFC7231] and MAY specify the desired response data format via an HTTP "Accept" header (Section 5.3.2 of [RFC7231]), e.g., "Accept: application/scim+json", or via URI suffix: GET /Users/2819c223-7f76-453a-919d-413861904646.scim Host: example.com Service providers MUST support the "Accept" header "Accept: application/scim+json" and SHOULD support the header "Accept: application/json", both of which specify JSON documents conforming to [RFC7159]. The format defaults to "application/scim+json" if no format is specified. Singular attributes are encoded as string name-value pairs in JSON, e.g., "attribute": "value" Multi-valued attributes in JSON are encoded as arrays, e.g., "attributes": [ "value1", "value2" ] Elements with nested elements are represented as objects in JSON, e.g., "attribute": { "subattribute1": "value1", "subattribute2": "value2" }3.9. Additional Operation Response Parameters
For any SCIM operation where a resource representation is returned (e.g., HTTP GET), the attributes returned are defined as the minimum attribute set plus default attribute set. The minimum set is composed of those attributes that have their "returned" characteristic set to "always" (see Section 2.2 of [RFC7643]). The default attribute set is composed of those attributes that have the "returned" characteristic set to "default".
Clients MAY request a partial resource representation on any
operation that returns a resource within the response by specifying
either of the mutually exclusive URL query parameters "attributes" or
"excludedAttributes", as follows:
attributes When specified, the default list of attributes SHALL be
overridden, and each resource returned MUST contain the
minimum set of resource attributes and any attributes or
sub-attributes explicitly requested by the "attributes"
parameter. The query parameter attributes value is a
comma-separated list of resource attribute names in standard
attribute notation (Section 3.10) form (e.g., userName, name,
emails).
excludedAttributes When specified, each resource returned MUST
contain the minimum set of resource attributes.
Additionally, the default set of attributes minus those
attributes listed in "excludedAttributes" is returned. The
query parameter attributes value is a comma-separated list of
resource attribute names in standard attribute notation
(Section 3.10) form (e.g., userName, name, emails).
GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
The following response is returned:
HTTP/1.1 200 OK
Content-Type: application/scim+json
Location:
https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"a330bc54f0671c9"
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646",
"userName":"bjensen"
}
3.10. Attribute Notation
All operations share a common scheme for referencing simple and complex attributes. In general, attributes are uniquely identified by prefixing the attribute name with its schema URN separated by a colon (":") character; e.g., the core User resource attribute 'userName' is identified as "urn:ietf:params:scim:schemas:core:2.0:User:userName". Clients MAY omit core schema attribute URN prefixes but SHOULD fully qualify extended attributes with the associated schema extension URN to avoid naming conflicts. For example, the attribute 'age' defined in "urn:ietf:params:scim:schemas:exampleCo:2.0:hr" is uniquely identified as "urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age". Complex attributes' sub-attributes are referenced via nested dot ('.') notation, i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For example, the fully qualified path for a User's givenName is "urn:ietf:params:scim:schemas:core:2.0:User:name.givenName". All facets (URN, attribute, and sub-attribute name) of the fully encoded attribute name are case insensitive.3.11. "/Me" Authenticated Subject Alias
A client MAY use a URL of the form "<base-URI>/Me" as a URI alias for the User or other resource associated with the currently authenticated subject for any SCIM operation. A service provider MAY respond in one of three ways: o A service provider that does NOT support this feature SHOULD respond with HTTP status code 501 (Not Implemented). o A service provider MAY choose to redirect the client using HTTP status code 308 (Permanent Redirect) to the resource associated with the authenticated subject. The client MAY then repeat the request at the indicated location. o A service provider MAY process the SCIM request directly. In any response, the HTTP "Location" header MUST be the permanent location of the aliased resource associated with the authenticated subject. When using the SCIM Create Resource command (HTTP POST) with the "/Me" alias, the desired resourceType being created is at the discretion of the service provider, based on the authenticated subject (if not anonymous) making the request and any request body attributes (e.g., "schemas"). See Section 7.6 for information on security considerations related to this operation.
3.12. HTTP Status and Error Response Handling
The SCIM protocol uses the HTTP response status codes defined in Section 6 of [RFC7231] to indicate operation success or failure. In addition to returning an HTTP response code, implementers MUST return the errors in the body of the response in a JSON format, using the attributes described below. Error responses are identified using the following "schema" URI: "urn:ietf:params:scim:api:messages:2.0:Error". The following attributes are defined for a SCIM error response using a JSON body: status The HTTP status code (see Section 6 of [RFC7231]) expressed as a JSON string. REQUIRED. scimType A SCIM detail error keyword. See Table 9. OPTIONAL. detail A detailed human-readable message. OPTIONAL. Implementers SHOULD handle the identified HTTP status codes as described below. +----------------+---------------+----------------------------------+ | Status | Applicability | Suggested Explanation | +----------------+---------------+----------------------------------+ | 307 (Temporary | GET, POST, | The client is directed to repeat | | Redirect) | PUT, PATCH, | the same HTTP request at the | | | DELETE | location identified. The client | | | | SHOULD NOT use the location | | | | provided in the response as a | | | | permanent reference to the | | | | resource and SHOULD continue to | | | | use the original request URI | | | | [RFC7231]. | | | | | | 308 (Permanent | GET, POST, | The client is directed to repeat | | Redirect) | PUT, PATCH, | the same HTTP request at the | | | DELETE | location identified. The client | | | | SHOULD use the location provided | | | | in the response as the permanent | | | | reference to the resource | | | | [RFC7538]. | | | | | | 400 (Bad | GET, POST, | Request is unparsable, | | Request) | PUT, PATCH, | syntactically incorrect, or | | | DELETE | violates schema. |
| | | | | 401 | GET, POST, | Authorization failure. The | | (Unauthorized) | PUT, PATCH, | authorization header is invalid | | | DELETE | or missing. | | | | | | 403 | GET, POST, | Operation is not permitted based | | (Forbidden) | PUT, PATCH, | on the supplied authorization. | | | DELETE | | | | | | | 404 (Not | GET, POST, | Specified resource (e.g., User) | | Found) | PUT, PATCH, | or endpoint does not exist. | | | DELETE | | | | | | | 409 (Conflict) | POST, PUT, | The specified version number | | | PATCH, DELETE | does not match the resource's | | | | latest version number, or a | | | | service provider refused to | | | | create a new, duplicate | | | | resource. | | | | | | 412 | PUT, PATCH, | Failed to update. Resource has | | (Precondition | DELETE | changed on the server. | | Failed) | | | | | | | | 413 (Payload | POST | {"maxOperations": | | Too Large) | | 1000,"maxPayloadSize": 1048576} | | | | | | 500 (Internal | GET, POST, | An internal error. Implementers | | Server Error) | PUT, PATCH, | SHOULD provide descriptive | | | DELETE | debugging advice. | | | | | | 501 (Not | GET, POST, | Service provider does not | | Implemented) | PUT, PATCH, | support the request operation, | | | DELETE | e.g., PATCH. | +----------------+---------------+----------------------------------+ Table 8: SCIM HTTP Status Code Usage
For HTTP status code 400 (Bad Request) responses, the following
detail error types are defined:
+---------------+--------------------------------+------------------+
| scimType | Description | Applicability |
+---------------+--------------------------------+------------------+
| invalidFilter | The specified filter syntax | GET (Section |
| | was invalid (does not comply | 3.4.2), POST |
| | with Figure 1), or the | (Search - |
| | specified attribute and filter | Section 3.4.3), |
| | comparison combination is not | PATCH (Path |
| | supported. | Filter - Section |
| | | 3.5.2) |
| | | |
| tooMany | The specified filter yields | GET (Section |
| | many more results than the | 3.4.2), POST |
| | server is willing to calculate | (Search - |
| | or process. For example, a | Section 3.4.3) |
| | filter such as "(userName pr)" | |
| | by itself would return all | |
| | entries with a "userName" and | |
| | MAY not be acceptable to the | |
| | service provider. | |
| | | |
| uniqueness | One or more of the attribute | POST (Create - |
| | values are already in use or | Section 3.3), |
| | are reserved. | PUT (Section |
| | | 3.5.1), PATCH |
| | | (Section 3.5.2) |
| | | |
| mutability | The attempted modification is | PUT (Section |
| | not compatible with the target | 3.5.1), PATCH |
| | attribute's mutability or | (Section 3.5.2) |
| | current state (e.g., | |
| | modification of an "immutable" | |
| | attribute with an existing | |
| | value). | |
| | | |
| invalidSyntax | The request body message | POST (Search - |
| | structure was invalid or did | Section 3.4.3, |
| | not conform to the request | Create - Section |
| | schema. | 3.3, Bulk - |
| | | Section 3.7), |
| | | PUT (Section |
| | | 3.5.1) |
| | | |
| invalidPath | The "path" attribute was | PATCH (Section | | | invalid or malformed (see | 3.5.2) | | | Figure 7). | | | | | | | noTarget | The specified "path" did not | PATCH (Section | | | yield an attribute or | 3.5.2) | | | attribute value that could be | | | | operated on. This occurs when | | | | the specified "path" value | | | | contains a filter that yields | | | | no match. | | | | | | | invalidValue | A required value was missing, | GET (Section | | | or the value specified was not | 3.4.2), POST | | | compatible with the operation | (Create - | | | or attribute type (see Section | Section 3.3, | | | 2.2 of [RFC7643]), or resource | Query - Section | | | schema (see Section 4 of | 3.4.3), PUT | | | [RFC7643]). | (Section 3.5.1), | | | | PATCH (Section | | | | 3.5.2) | | | | | | invalidVers | The specified SCIM protocol | GET (Section | | | version is not supported (see | 3.4.2), POST | | | Section 3.13). | (ALL), PUT | | | | (Section 3.5.1), | | | | PATCH (Section | | | | 3.5.2), DELETE | | | | (Section 3.6) | | | | | | sensitive | The specified request cannot | GET (Section | | | be completed, due to the | 3.4.2) | | | passing of sensitive (e.g., | | | | personal) information in a | | | | request URI. For example, | | | | personal information SHALL NOT | | | | be transmitted over request | | | | URIs. See Section 7.5.2. | | +---------------+--------------------------------+------------------+ Table 9: SCIM Detail Error Keyword Values Note that in Table 9 above, the information in the Applicability column applies to the normal HTTP method but MAY apply within a SCIM bulk operation (via HTTP POST).
Example of an error in response to a non-existent GET request:
HTTP/1.1 404 Not Found
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
"status": "404"
}
Example of an error in response to a PUT request:
HTTP/1.1 400 Bad Request
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"mutability"
"detail":"Attribute 'id' is readOnly",
"status": "400"
}
3.13. SCIM Protocol Versioning
The Base URL MAY be appended with a version identifier as a separate
segment in the URL path. At the time of this writing, the identifier
is 'v2'. If specified, the version identifier MUST appear in the URL
path immediately preceding the resource endpoint and conform to the
following scheme: the character 'v' followed by the desired SCIM
version number, e.g., a version 'v2' User request is specified as
/v2/Users. When specified, service providers MUST perform the
operation using the desired version or reject the request. When
omitted, service providers SHOULD perform the operation using the
most recent SCIM protocol version supported by the service provider.
3.14. Versioning Resources
The SCIM protocol supports resource versioning via standard HTTP
ETags (Section 2.3 of [RFC7232]). Service providers MAY support weak
ETags as the preferred mechanism for performing conditional
retrievals and ensuring that clients do not inadvertently overwrite
each other's changes, respectively. When supported, SCIM ETags MUST
be specified as an HTTP header and SHOULD be specified within the
'version' attribute contained in the resource's 'meta' attribute.
Example create request:
POST /Users HTTP/1.1
Host: example.com
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName":"bjensen",
"externalId":"bjensen",
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
}
}
The server responds with an ETag in the response header and meta
structure:
HTTP/1.1 201 Created
Content-Type: application/scim+json
Location:
https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1"
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"id":"2819c223-7f76-453a-919d-413861904646",
"meta":{
"resourceType":"User",
"created":"2011-08-01T21:32:44.882Z",
"lastModified":"2011-08-01T21:32:44.882Z",
"location":
"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"e180ee84f0671b1\""
},
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
},
"userName":"bjensen"
}
With the returned ETag, clients MAY choose to retrieve the resource only if the resource has been modified. An example of conditional retrieval, using the If-None-Match header (Section 3.2 of [RFC7232]): GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName Host: example.com Accept: application/scim+json Authorization: Bearer h480djs93hd8 If-None-Match: W/"e180ee84f0671b1" If the resource has not changed, the service provider simply returns an empty body with a 304 (Not Modified) response code. If the service provider supports versioning of resources, the client MAY supply an If-Match header (Section 3.1 of [RFC7232]) for PUT and PATCH operations to ensure that the requested operation succeeds only if the supplied ETag matches the latest service provider resource, e.g., If-Match: W/"e180ee84f0671b1".4. Service Provider Configuration Endpoints
SCIM defines three endpoints to facilitate discovery of SCIM service provider features and schema that MAY be retrieved using HTTP GET: /ServiceProviderConfig An HTTP GET to this endpoint will return a JSON structure that describes the SCIM specification features available on a service provider. This endpoint SHALL return responses with a JSON object using a "schemas" attribute of "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig". The attributes returned in the JSON object are defined in Section 5 of [RFC7643]. An example representation of SCIM service provider configuration may be found in Section 8.5 of [RFC7643].
/Schemas
An HTTP GET to this endpoint is used to retrieve information about
resource schemas supported by a SCIM service provider. An HTTP
GET to the endpoint "/Schemas" SHALL return all supported schemas
in ListResponse format (see Figure 3). Individual schema
definitions can be returned by appending the schema URI to the
/Schemas endpoint. For example:
/Schemas/urn:ietf:params:scim:schemas:core:2.0:User
The contents of each schema returned are described in Section 7 of
[RFC7643]. An example representation of SCIM schemas may be found
in Section 8.7 of [RFC7643].
/ResourceTypes
An HTTP GET to this endpoint is used to discover the types of
resources available on a SCIM service provider (e.g., Users and
Groups). Each resource type defines the endpoints, the core
schema URI that defines the resource, and any supported schema
extensions. The attributes defining a resource type can be found
in Section 6 of [RFC7643], and an example representation can be
found in Section 8.6 of [RFC7643].
In cases where a request is for a specific "ResourceType" or
"Schema", the single JSON object is returned in the same way that a
single User or Group is retrieved, as per Section 3.4.1. When
returning multiple ResourceTypes or Schemas, the message form
described by the "urn:ietf:params:scim:api:messages:2.0:ListResponse"
(ListResponse) form SHALL be used as shown in Figure 3 and in
Figure 9 below. Query parameters described in Section 3.4.2, such as
filtering, sorting, and pagination, SHALL be ignored. If a "filter"
is provided, the service provider SHOULD respond with HTTP status
code 403 (Forbidden) to ensure that clients cannot incorrectly assume
that any matching conditions specified in a filter are true.
The following is a non-normative example of an HTTP GET to the /ResourceTypes endpoint: { "totalResults":2, "itemsPerPage":10, "startIndex":1, "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "Resources":[{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"], "id":"User", "name":"User", "endpoint": "/Users", "description": "User Account", "schema": "urn:ietf:params:scim:schemas:core:2.0:User", "schemaExtensions": [{ "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", "required": true }], "meta": { "location":"https://example.com/v2/ResourceTypes/User", "resourceType": "ResourceType" } }, { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"], "id":"Group", "name":"Group", "endpoint": "/Groups", "description": "Group", "schema": "urn:ietf:params:scim:schemas:core:2.0:Group", "meta": { "location":"https://example.com/v2/ResourceTypes/Group", "resourceType": "ResourceType" } }] } Figure 9: Example Resource Type JSON Representation
(next page on part 4)
