This page (revision-1) was last changed on 29-Nov-2024 16:16 by UnknownAuthor

Only authorized users are allowed to rename pages.

Only authorized users are allowed to delete pages.

Page revision history

Version Date Modified Size Author Changes ... Change note

Page References

Incoming links Outgoing links
SCIM Bulk Request
SCIM Bulk Request

Version management

Difference between version and

At line 1 added 534 lines
!!! Overview
[{$pagename}] operation enables [SCIM Clients] to send a potentially large collection of [SCIM Resource Operations] in a single request.
The body of a bulk operation contains a set of [HTTP] Resource operations using one of the API supported HTTP methods:
* [HTTP POST]
* [HTTP PUT]
* [HTTP PATCH]
* [HTTP DELETE].
[{$pagename}] is __OPTIONAL__
The following Singular Attribute is defined in addition to the common attributes defined in SCIM core schema.
! failOnErrors
An Integer specifying the number of errors that the [SCIM Service Provider] will accept before the operation is terminated and an error response is returned. __OPTIONAL__
The following Complex Multi-valued Attribute is defined in addition to the common attributes defined in core schema.
* Operations - Defines operations within a bulk job. Each operation corresponds to a single HTTP request against a Resource endpoint. __REQUIRED__.
* 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 [SCIM Client]. The bulkId serves as a surrogate Resource id enabling [SCIM Client]s 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 is __REQUIRED__ if the Service Provider supports ETags and the method is PUT, DELETE, or PATCH.
* path - The Resource's relative path. If the 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 POST, PUT or PATCH Resource operation. __REQUIRED__ in a request when method is POST, PUT and PATCH.
* location - The Resource endpoint URL. __REQUIRED__ in a response, except in the event of a POST failure.
* status - A complex type that contains information about the success or failure of one operation within the bulk job. __REQUIRED__ in a response.
** code - The HTTP response code that would have been returned if a single [HTTP] request would have been used. __REQUIRED__.
** description - A human readable error message. __REQUIRED__ when an error occurred.
If a bulk job is processed successfully the HTTP response code 200 OK __MUST__ be returned, otherwise an appropriate [HTTP Status Code] __MUST__ be returned.
The [SCIM Service Provider] __MUST__ continue performing as many changes as possible and disregard partial failures. The [SCIM Client] __MAY__ override this behavior by specifying a value for failOnErrors attribute. The failOnErrors attribute defines the number of errors that the [SCIM Service Provider] should accept before failing the remaining operations returning the response.
To be able to reference a newly created Resource the attribute bulkId __MUST__ be specified when creating new Resources. The bulkId is defined by the [SCIM Client] as a surrogate identifier in a POST operation. The [SCIM Service Provider] __MUST__ return the same bulkId together with the newly created Resource. The bulkId can then be used by the [SCIM Client] to map the [SCIM Service Provider] id with the bulkId of the created Resource.
There can be more then one operation per Resource in each bulk job. The Service [SCIM Client] __MUST__ take notice of the unordered structure of JSON and the [SCIM Service Provider] can process operations in any order. For example, if the Service [SCIM Client] sends two PUT operations in one request, the outcome is non-deterministic.
The [SCIM Service Provider] response __MUST__ include the result of all processed operations. A location attribute that includes the Resource's end point __MUST__ be returned for all operations excluding failed POSTs. The status attribute includes information about the success or failure of one operation within the bulk job. The attribute status __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.
%%prettify
{{{
"status": {
"code": "201"
}
}}} /%
The following is an example of a status in a failed operation.
%%prettify
{{{
"status": {
"code": "400",
"description": "Request is unparseable, syntactically incorrect, or violates schema."
}
}}} /%
The following example shows how to add, update, and remove a user. The failOnErrors attribute is set to '1' indicating the [SCIM Service Provider] should return on the first error. The POST operation's bulkId value is set to 'qwerty' enabling the [SCIM Client] to match the new User with the returned Resource id '92b725cd-9465-4e7d-8c16-01f8e146b87a'.
%%prettify
{{{
POST /v1/Bulk
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas":[
"urn:scim:schemas:core:1.0"
],
"failOnErrors":1,
"Operations":[
{
"method":"POST",
"path":"/Users",
"bulkId":"qwerty",
"data":{
"schemas":[
"urn:scim:schemas:core:1.0"
],
"userName":"Alice"
}
},
{
"method":"PUT",
"path":"/Users/b7c14771-226c-4d05-8860-134711653041",
"version":"W\/\"3694e05e9dff591\"",
"data":{
"schemas":[
"urn:scim:schemas:core:1.0"
],
"id":"b7c14771-226c-4d05-8860-134711653041",
"userName":"Bob"
}
},
{
"method":"PATCH",
"path":"/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"version":"W\/\"edac3253e2c0ef2\"",
"data":{
"schemas":[
"urn:scim:schemas:core:1.0"
],
"id":"5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"userName":"Dave",
"meta":{
"attributes":[
"nickName"
]
}
}
},
{
"method":"DELETE",
"path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"version":"W\/\"0ee8add0a938e1a\""
}
]
}
}}} /%
The [SCIM Service Provider] returns the following response.
%%prettify
{{{
HTTP/1.1 200 OK
Content-Type: application/json
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"Operations": [
{
"location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST",
"bulkId": "qwerty",
"version": "W\/\"oY4m4wn58tkVjJxK\"",
"status": {
"code": "201"
}
},
{
"location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT",
"version": "W\/\"huJj29dMNgu3WXPD\"",
"status": {
"code": "200"
}
},
{
"location": "https://example.com/v1/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH",
"version": "W\/\"huJj29dMNgu3WXPD\"",
"status": {
"code": "200"
}
},
{
"location": "https://example.com/v1/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE",
"status": {
"code": "200"
}
}
]
}
}}} /%
The following response is returned if an error occurred when attempting to create the User 'Alice'. The [SCIM Service Provider] stops processing the bulk operation and immediately returns a response to the [SCIM Client]. The response contains the error and any successful results prior to the error.
%%prettify
{{{
HTTP/1.1 200 OK
Content-Type: application/json
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"Operations": [
{
"method": "POST",
"bulkId": "qwerty",
"status": {
"code": "400",
"description": "Request is unparseable, syntactically incorrect, or violates schema."
}
}
]
}
}}} /%
If the failOnErrors attribute is not specified or the [SCIM Service Provider] has not reached the error limit defined by the [SCIM Client] the [SCIM Service Provider] will continue to process all operations. The following is an example in which all operations failed.
%%prettify
{{{
HTTP/1.1 200 OK
Content-Type: application/json
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"Operations": [
{
"method": "POST",
"bulkId": "qwerty",
"status": {
"code": "400",
"description": "Request is unparseable, syntactically incorrect, or violates schema."
}
},
{
"location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT",
"status": {
"code": "412",
"description": "Failed to update as user changed on the server since you last retrieved it."
}
},
{
"location": "https://example.com/v1/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH",
"status": {
"code": "412",
"description": "Failed to update as user changed on the server since you last retrieved it."
}
},
{
"location": "https://example.com/v1/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE",
"status": {
"code": "404",
"description": "Specified resource; e.g., User, does not exist."
}
}
]
}
}}} /%
The [SCIM 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 [SCIM 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 [SCIM 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.
%%prettify
{{{
POST /v1/Bulk
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"Operations": [
{
"method": "POST",
"path": "/Users",
"bulkId": "qwerty",
"data": {
"schemas": [
"urn:scim:schemas:core:1.0"
],
"userName": "Alice"
}
},
{
"method": "POST",
"path": "/Groups",
"bulkId": "ytrewq",
"data": {
"schemas": [
"urn:scim:schemas:core:1.0"
],
"displayName": "Tour Guides",
"members": [
{
"type": "user",
"value": "bulkId:qwerty"
}
]
}
}
]
}
}}} /%
The [SCIM Service Provider] returns the following response.
%%prettify
{{{
HTTP/1.1 200 OK
Content-Type: application/json
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"Operations": [
{
"location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST",
"bulkId": "qwerty",
"version": "W\/\"4weymrEsh5O6cAEK\"",
"status": {
"code": "201"
}
},
{
"location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"method": "POST",
"bulkId": "ytrewq",
"version": "W\/\"lha5bbazU3fNvfe5\"",
"status": {
"code": "201"
}
}
]
}
}}} /%
A subsequent request for the 'Tour Guides' Group ('e9e30dba-f08f-4109-8486-d5c6a331660a') returns the following:
%%prettify
{{{
GET /v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
HTTP/1.1 200 OK
Content-Type: application/json
Location: https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
ETag: W/"lha5bbazU3fNvfe5"
{
"schemas":["urn:scim:schemas:core:1.0"],
"id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
"displayName": "Tour Guides",
"meta": {
"created":"2011-08-01T18:29:49.793Z",
"lastModified":"2011-08-01T20:31:02.315Z",
"location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"version": "W\/\"lha5bbazU3fNvfe5\""
},
"members": [
{
"value": "92b725cd-9465-4e7d-8c16-01f8e146b87a",
"type": "user"
}
]
}
}}} /%
Extensions that include references to other Resources __MUST__ be handled in the same way by the [SCIM Service Provider]. The following example uses the bulkId attribute within the enterprise extension managerId attribute.
%%prettify
{{{
POST /v1/Bulk
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"Operations": [
{
"method": "POST",
"path": "/Users",
"bulkId": "qwerty",
"data": {
"schemas": [
"urn:scim:schemas:core:1.0"
],
"userName": "Alice"
}
},
{
"method": "POST",
"path": "/Users",
"bulkId": "ytrewq",
"data": {
"schemas": [
"urn:scim:schemas:core:1.0",
"urn:scim:schemas:extension:enterprise:1.0"
],
"userName": "Bob",
"urn:scim:schemas:extension:enterprise:1.0": {
"employeeNumber": "11250",
"manager": {
"managerId": "batchId:qwerty",
"displayName": "Alice"
}
}
}
}
]
}
}}} /%
The [SCIM 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.
%%prettify
{{{
POST /v1/Bulk
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"Operations": [
{
"method": "POST",
"path": "/Groups",
"bulkId": "qwerty",
"data": {
"schemas": [
"urn:scim:schemas:core:1.0"
],
"displayName": "Group A",
"members": [
{
"type": "group",
"value": "bulkId:ytrewq"
}
]
}
},
{
"method": "POST",
"path": "/Groups",
"bulkId": "ytrewq",
"data": {
"schemas": [
"urn:scim:schemas:core:1.0"
],
"displayName": "Group B",
"members": [
{
"type": "group",
"value": "bulkId:qwerty"
}
]
}
}
]
}
}}} /%
If the [SCIM Service Provider] resolved the above circular references the following is returned from a subsequent GET request.
%%prettify
{{{
GET /v1/Groups?filter=displayName sw 'Group'
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
HTTP/1.1 200 OK
Content-Type: application/json
{
"totalResults": 2,
"schemas": [
"urn:scim:schemas:core:1.0"
],
"Resources": [
{
"id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"schemas": [
"urn:scim:schemas:core:1.0"
],
"displayName": "Group A",
"meta": {
"created":"2011-08-01T18:29:49.793Z",
"lastModified":"2011-08-01T18:29:51.135Z",
"location":"https://example.com/v1/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"version":"W\/\"mvwNGaxB5SDq074p\""
},
"members": [
{
"value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"type": "group"
}
]
},
{
"id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"schemas": [
"urn:scim:schemas:core:1.0"
],
"displayName": "Group B",
"meta": {
"created":"2011-08-01T18:29:50.873Z",
"lastModified":"2011-08-01T18:29:50.873Z",
"location":"https://example.com/v1/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"version":"W\/\"wGB85s2QJMjiNnuI\""
},
"members": [
{
"value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"type": "group"
}
]
}
]
}
}}} /%
The [SCIM Service Provider] __MUST__ define a limit on how many operations can be sent in one bulk request. The [SCIM Service Provider] __MUST__ also define the max payload size of a bulk request. If either limits are exceeded the [SCIM Service Provider] __MUST__ return the HTTP response code 413 Request Entity Too Large. The returned response must also include the attributes maxOperations and maxPayloadSize with the limits accepted by the [SCIM Service Provider].
In the following example the [SCIM Client] sent a request that exceeded the [SCIM Service Provider]'s max payload size 1 megabyte.
%%prettify
{{{
POST /v1/Bulk
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
Content-Length: 4294967296
…
HTTP/1.1 413 Request Entity Too Large
Content-Type: application/json
Location: https://example.com/v1/Bulk/yfCrVJhFIJagAHj8
{
"maxOperations": 1000,
"maxPayload": 1048576
}
}}} /%
!! More Information
There might be more information for this subject on one of the following:
[{ReferringPagesPlugin before='*' after='\n' }]
This page (revision-1) was last changed on 29-Nov-2024 16:16 by UnknownAuthorTop