Rate this page

Requesting, creating, and modifying resources

SCIM 2 CRUD operations are quite simple and require little explanation. They map to HTTP methods as follows:

Resource operation HTTP method
Retrieve GET
Create POST
Replace PUT
Modify PATCH
Delete DELETE

In the following examples, we’ll use GenericScimResource to give you a better idea of how the class is used. But do bear in mind that you can also use simpler classes derived from BaseScimResource.

Create a resource

To create a resource, create an instance of GenericScimResource or an instance of a BaseScimResource subclass. Set the object’s attributes as needed, then call ScimService.create(...) or ScimService.createRequest(...).

Note how the JsonUtils.valueToNode(...) utility method is used here to convert the Name and Email POJOs to JsonNode instances.

GenericScimResource user = new GenericScimResource();
user.setSchemaUrns(Collections.singletonList("urn:pingidentity:schemas:User:1.0"));
user.replaceValue("userName", "octavia");
user.replaceValue("password", "june-9");
Name name = new Name().setFamilyName("Butler").setGivenName("Octavia");
user.replaceValue("name", JsonUtils.valueToNode(name));
Email email = new Email().setType("home").setValue("octavia@example.com");
user.addValues("emails", JsonUtils.valueToNode(Collections.singleton(email)));
user = scimService.create("Users", user);

Retrieve a resource

The ScimService.retrieve(...) or ScimService.retrieveRequest(...) method retrieves a SCIM resource.

Note how the JsonUtils.nodeToValue(...) utility method is used here to convert JsonNode instances to POJOs.

final String id = "2819c223-7f76-453a-919d-413861904646";
GenericScimResource user =
  scimService.retrieve("Users", id, GenericScimResource.class);
String userName = user.getStringValue("userName");
Name name = JsonUtils.nodeToValue(user.getValue("name"), Name.class);
List<Email> emails =
    JsonUtils.nodeToValues((ArrayNode) user.getValue("emails"), Email.class);

Replace a resource

To replace a resource using PUT, call ScimService.replace(...) or ScimService.replaceRequest(...). The object that you provide will be used to update the existing resource.

final String id = "2819c223-7f76-453a-919d-413861904646";
GenericScimResource user =
  scimService.retrieve("Users", id, GenericScimResource.class);
Email email = new Email().setType("home").setValue("butler@example.com");
user.replaceValue("emails", JsonUtils.valueToNode(Collections.singleton(email)));
scimService.replace(user);

Modify a resource

You can also update a user with a partial modification using PATCH. Unlike the other operation types, partial modifications can be complex and should be used with care.

Partial modifications are performed using ScimService.modify(...) or ScimService.modifyRequest(...). The key to performing partial modifications is understanding what kind of node is targeted by the attribute path used in the request: A node representing a simple value, an object node, or an array node. The value provided for the modification must be appropriate for the path.

The following example updates a simple value at the path name.givenName.

final String id = "2819c223-7f76-453a-919d-413861904646";
GenericScimResource user = scimService.modifyRequest("Users", id)
    .replaceValue("name.givenName", "O")
    .invoke(GenericScimResource.class);

The following example shows how a modification request may include multiple modifications. The second modification updates an array node with two objects.

final String id = "2819c223-7f76-453a-919d-413861904646";

Email homeEmail = new Email().setType("home").setValue("octavia@example.com");
Email workEmail = new Email().setType("work").setValue("o.butler@example.com");

GenericScimResource user = scimService.modifyRequest("Users", id)
    .replaceValue("name.givenName", "O")
    .replaceValue("emails", JsonUtils.valueToNode(Arrays.asList(homeEmail, workEmail)))
    .invoke(GenericScimResource.class);

Partial modifications can be performed in numerous other ways. See the SCIM 2 SDK wiki for more examples.

Delete a resource

To delete a resource, simply call ScimService.delete(...) or ScimService.deleteRequest(...).

final String id = "2819c223-7f76-453a-919d-413861904646";
scimService.delete("Users", id);

Authorization

Creating a resource requires a resource scope. All other operations work with either authenticated identity scopes or resource scopes.