Overview#

SCIM Update Request is a SCIM Resource Operation to UPDATE a SCIM Resource

Modifications to an existing SCIM Resource can be performed with either a SCIM Update Request or a SCIM Replace Request.

Modifying with PATCH#

PATCH is OPTIONAL.

PATCH enables SCIM Clients to send only those attributes requiring modification, reducing network and processing overhead. Attributes may be

  • deleted
  • replaced
  • merged
  • or added in a single request.

The body of a PATCH request MUST contain a partial SCIM Resource with the desired modifications.

The SCIM Service Provider MUST return either a HTTP Status Code 200 OK response code and the entire SCIM Resource (subject to the "attributes" query parameter - see Additional Retrieval Query Parameters) within the response body, or a 204 No Content HTTP Status Code and the appropriate response headers for a successful PATCH request. The server MUST return a 200 OK HTTP Status Code if the "attributes" parameter is specified on the request.

The SCIM Service Provider MUST process a PATCH request by first removing any attributes specified in the meta.attributes Sub-Attribute (if present) and then merging the attributes in the PATCH request body into the SCIM Resource.

The meta.attributes Sub-Attribute MAY contain a list of attributes to be removed from the SCIM Resource. If the PATCH request body contains an attribute that is present in the meta.attributes list, the attribute on the SCIM Resource is replaced with the value from the HTTP PATCH body. If the attribute is complex the attribute name must be a path to a Sub-Attribute in standard attribute notation; e.g., name.givenName.

Attributes that exist in the PATCH request body but not in the meta.attributes Sub-Attribute will be either be updated or added to the SCIM Resource according to the following rules.

Singular attributes#

Singular attributes in the PATCH request body replace the attribute on the SCIM Resource.

Complex attributes#

Complex Sub Attribute values in the HTTP PATCH request body are merged into the complex attribute on the SCIM Resource.

Multi-valued attributes #

An attribute value in the HTTP PATCH request body is added to the value collection if the value does not exist and merged if a matching value is present. Values are matched by comparing the value Sub-Attribute from the PATCH request body to the value Sub-Attribute of the SCIM Resource.

Attributes that do not have a value Sub-Attribute; e.g., addresses, or do not have unique value Sub-Attributes cannot be matched and must instead be deleted then added.

Specific values can be removed from a SCIM Resource by adding an "operation" Sub-Attribute with the value "delete" to the attribute in the HTTP PATCH request body. As with adding/updating attribute value collections, the value to delete is determined by comparing the value Sub-Attribute from the PATCH request body to the value Sub-Attribute of the SCIM Resource.

Attributes that do not have a value Sub-Attribute or that have a non-unique value Sub-Attribute are matched by comparing all Sub-Attribute values from the PATCH request body to the Sub-Attribute values of the SCIM Resource.

A delete operation is ignored if the attribute's name is in the meta.attributes list. If the requested value to delete does not match a unique value on the SCIM Resource the server MAY return a HTTP Status Code 400 error.

SCIM Update Request example shows how to add a member to a SCIM Group:

PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
ETag: W/"a330bc54f0671c9"

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "members": [
    {
      "display": "Babs Jensen",
      "value": "2819c223-7f76-453a-919d-413861904646"
    }
  ]
}

The "display" Sub-Attribute in this request is optional since the value attribute uniquely identifies the user to be added. If the user was already a member of this group, no changes should be made to the SCIM Resource and a success response should be returned. The SCIM Service Provider responds with either the entire updated SCIM Group or no response body:

HTTP/1.1 204 No Content
Authorization: Bearer h480djs93hd8
ETag: W/"b431af54f0671a2"
Location: "https://example.com/v1/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce"

The following example shows how to remove a member from a SCIM Group. As with the previous example, the "display" Sub-Attribute is optional. If the user was not a member of this SCIM Group, no changes should be made to the Resource and a success response should be returned.

Note that SCIM Service Provider responses have been omitted for the rest of the HTTP PATCH examples.
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
ETag: W/"a330bc54f0671c9"

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "members": [
    {
      "display": "Babs Jensen",
      "value": "2819c223-7f76-453a-919d-413861904646"
      "operation": "delete"
    }
  ]
}

The following example shows how to remove all members from a SCIM Group:

PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
ETag: W/"a330bc54f0671c9"

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "meta": {
    "attributes": [
      "members"
    ]
  }
}

The following example shows how to replace all of the members of a roup

PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
ETag: W/"a330bc54f0671c9"

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "meta": {
    "attributes": [
      "members"
    ]
  },
  "members": [
    {
      "display": "Babs Jensen",
      "value": "2819c223-7f76-453a-919d-413861904646"
    },
    {
      "display": "James Smith",
      "value": "08e1d05d-121c-4561-8b96-473d93df9210"
    }
  ]
}

The following example shows how to add a member to and remove a member from a SCIM Group in a single request:

PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
ETag: W/"a330bc54f0671c9"

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "members": [
    {
      "display": "Babs Jensen",
      "value": "2819c223-7f76-453a-919d-413861904646"
      "operation": "delete"
    },
    {
      "display": "James Smith",
      "value": "08e1d05d-121c-4561-8b96-473d93df9210"
    }
  ]
}

The following example shows how to change a User's primary email. If the User already has the email address, it is made the primary address and the current primary address (if present) is made non-primary. If the User does not already have the email address, it is added and made the primary address.

PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
ETag: "a330bc54f0671c9"

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "emails": [
    {
      "value": "bjensen@example.com",
      "primary": true
    }
  ]
}

The following example shows how to change a User's address. Since address does not have a value Sub-Attribute, the existing address must be removed and the modified address added.

PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
ETag: W/"a330bc54f0671c9"

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "addresses": [
    {
      "type": "work",
      "streetAddress": "100 Universal City Plaza",
      "locality": "Hollywood",
      "region": "CA",
      "postalCode": "91608",
      "country": "US",
      "formatted": "100 Universal City Plaza\nHollywood, CA 91608 US",
      "primary": true
      "operation": "delete"
    },
    {
      "type": "work",
      "streetAddress": "911 Universal City Plaza",
      "locality": "Hollywood",
      "region": "CA",
      "postalCode": "91608",
      "country": "US",
      "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US",
      "primary": true
    }
  ]
}

The following example shows how to change a User's nickname:

PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
ETag: W/"a330bc54f0671c9"

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "nickName": "Barbie"
}
The following example shows how to remove a User's nickname:

PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
ETag: W/"a330bc54f0671c9"

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "meta": {
    "attributes": [
      "nickName"
    ]
  }
}

The following example shows how to change a User's familyName. This only updates the familyName and formatted on the "name" complex attribute. Any other name Sub-Attributes on the SCIM Resource remain unchanged.

PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
ETag: W/"a330bc54f0671c9"

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "name": {
    "formatted": "Ms. Barbara J Jensen III",
    "familyName": "Jensen"
  }
}

The following example shows how to remove a complex Sub-Attribute and an extended schema attribute from a User.

PATCH /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
ETag: W/"a330bc54f0671c9"

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "meta": {
    "attributes": [
      "name.formatted",
      "urn:hr:schemas:user:age"
    ]
  }
}

More Information#

There might be more information for this subject on one of the following:

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-5) was last changed on 22-May-2016 04:38 by jim