Skip to content

Commit a2a909a

Browse files
mmutadichmmutadich
authored
Add Scim/Users/Bulk endpoint documentation (#148)
1 parent 29722ed commit a2a909a

File tree

1 file changed

+182
-0
lines changed
  • content/en/docs/reference/api/scim-api

1 file changed

+182
-0
lines changed

‎content/en/docs/reference/api/scim-api/_index.md

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ Resources defined in the [SCIM core schema specification][scim-core-schema].
2727
IAM implements the following SCIM endpoints:
2828

2929
- `/scim/Users`, providing access to user account resources;
30+
- `/scim/Users/Bulk`, providing access to bulk user operations in a single request;
3031
- `/scim/Groups`, providing access to group resources;
3132
- `/scim/Me`, providing access to the user account resource for the currently
3233
authenticated user.
@@ -843,6 +844,187 @@ Example: Client attempt to retrieve the previously deleted User:
843844
]
844845
}
845846

847+
## POST `/scim/Users/Bulk`
848+
849+
Requires `scim:write` scope.
850+
851+
This endpoint allows consumers to execute multiple operations through one request, reducing network and processing overhead. Users may be created or updated in bulk using the `POST` and `PATCH` HTTP methods.
852+
853+
The body of this request MUST contain a list of operations where each operation includes a supported HTTP method (`POST` or `PATCH` only). The body of each operation MUST also contain a `path` attribute with the resource’s relative path to the SCIM service provider’s root and a `data` attribute with the resources required for a single `POST` or `PATCH` operation. `POST` operations MUST include a `bulkId` attribute to uniquely identify the new resource for cross-referencing within the same request.
854+
855+
If the request is successful, a 200 OK response code will be returned containing the result of all processed operations. Each operation response contains a `status` attribute that details the HTTP response status code of the requested operation. If the `status` of the operation response is not within the 200-series, it will also contain a response body. If the requested operation is successful, its response will include a `location` attribute with the resource’s endpoint. If the requested operation is unsuccessful, the response body will contain the details of the error.
856+
857+
Example with two bulk operations: the first uses the `POST` method to create a user and the second uses the `PATCH` method to update user credentials.
858+
859+
POST http://localhost:8080/scim/Users/Bulk
860+
861+
```json
862+
{
863+
"schemas": [
864+
"urn:ietf:params:scim:api:messages:2.0:BulkRequest"
865+
],
866+
"operations": [
867+
{
868+
"method": "POST",
869+
"path": "/Users",
870+
"bulkId": "qwerty",
871+
"data": {
872+
"id": "75ad58a5-1d1f-f77e-0f3e-4f9d5e45ae35",
873+
"schemas": [
874+
"urn:ietf:params:scim:schemas:core:2.0:User"
875+
],
876+
"displayName": "Patrick Star",
877+
"name": {
878+
"givenName": "Patrick",
879+
"familyName": "Star",
880+
"middleName": ""
881+
},
882+
"emails": [
883+
{
884+
"type": "work",
885+
"value": "patrick@star.com",
886+
"primary": true
887+
}
888+
],
889+
"userName": "partickstar",
890+
"active": true,
891+
"picture": ""
892+
}
893+
},
894+
{
895+
"method": "PATCH",
896+
"path": "/Users/73f16d93-2441-4a50-88ff-85360d78c6b5",
897+
"data": {
898+
"schemas": [
899+
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
900+
],
901+
"operations": [
902+
{
903+
"op": "add",
904+
"value": {
905+
"displayName": "Paul McCartney",
906+
"name": {
907+
"givenName": "Paul",
908+
"familyName": "McCartney",
909+
"middleName": ""
910+
}
911+
}
912+
}
913+
]
914+
}
915+
}
916+
]
917+
}
918+
```
919+
All operations are executed even if there are partial failures. In the example request, the `POST` operation is expected to fail as the user already exists. The returned response is:
920+
921+
HTTP/1.1 200 OK
922+
Content-Type: application/scim+json;charset=UTF-8
923+
```json
924+
{
925+
"schemas": [
926+
"urn:ietf:params:scim:api:messages:2.0:BulkResponse"
927+
],
928+
"operations": [
929+
{
930+
"method": "POST",
931+
"status": "409",
932+
"bulkId": "qwerty",
933+
"errorResponse": {
934+
"status": "409",
935+
"detail": "A user with username 'partickstar' already exists",
936+
"schemas": [
937+
"urn:ietf:params:scim:api:messages:2.0:Error"
938+
]
939+
}
940+
},
941+
{
942+
"method": "PATCH",
943+
"status": "200",
944+
"location": "/Users/73f16d93-2441-4a50-88ff-85360d78c6b5"
945+
}
946+
]
947+
}
948+
```
949+
950+
The bulkId attribute, which is REQUIRED for all `POST` operations, MUST be unique within the request. It should not contain personally identifiable information as it may appear in logs or error messages. Resources created by a `POST` operation can be referenced in subsequent operations using the `bulkId`, with the prefix `bulkId:`, to update users that are being created in the same bulk request.
951+
952+
An example of a request where a user is created and later updated using the bulkId in the operation path `/Users/bulkid:qwerty`.
953+
954+
POST http://localhost:8080/scim/Users/Bulk
955+
956+
```json
957+
{
958+
"schemas": [
959+
"urn:ietf:params:scim:api:messages:2.0:BulkRequest"
960+
],
961+
"operations": [
962+
{
963+
"method": "POST",
964+
"path": "/Users",
965+
"bulkId": "qwerty",
966+
"data": {
967+
"id": "75ad58a5-1d1f-f77e-0f3e-4f9d5e45ae35",
968+
"schemas": [
969+
"urn:ietf:params:scim:schemas:core:2.0:User"
970+
],
971+
"displayName": "Patrick Star",
972+
"name": {
973+
"givenName": "Patrick",
974+
"familyName": "Star",
975+
"middleName": ""
976+
},
977+
"emails": [
978+
{
979+
"type": "work",
980+
"value": "patrick@star.com",
981+
"primary": true
982+
}
983+
],
984+
"userName": "partickstar",
985+
"active": true,
986+
"picture": ""
987+
}
988+
},
989+
{
990+
"method": "PATCH",
991+
"path": "/Users/bulkid:qwerty",
992+
"data": {
993+
"schemas": [
994+
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
995+
],
996+
"operations": [
997+
{
998+
"op": "add",
999+
"value": {
1000+
"displayName": "Paul McCartney",
1001+
"name": {
1002+
"givenName": "Paul",
1003+
"familyName": "McCartney",
1004+
"middleName": ""
1005+
}
1006+
}
1007+
}
1008+
]
1009+
}
1010+
}
1011+
]
1012+
}
1013+
```
1014+
If the client specifies the optional failOnErrors attribute, the request will terminate once the number of failures exceeds this value and an error code response will be returned. If the number of operations in the request exceeds the maximum, an HTTP 413 PAYLOAD TOO LARGE response code will be returned, including the maximum number of allowed operations.
1015+
1016+
HTTP/1.1 413 PAYLOAD TOO LARGE
1017+
Content-Type: application/json
1018+
```json
1019+
{
1020+
"status": "413",
1021+
"detail": "Maximum number of operations exceeded (500)",
1022+
"schemas": [
1023+
"urn:ietf:params:scim:api:messages:2.0:Error"
1024+
]
1025+
}
1026+
```
1027+
8461028
## GET `/scim/Groups/{id}`
8471029

8481030
Retrieves information about the group identified by `id` and returns results in

0 commit comments

Comments
 (0)