Rate this page

SCIM 2 SDK for Java

In the next few articles, we’ll go over some examples of the Data Governance Broker’s key resource server APIs. But first, we’ll take a brief look at the SCIM 2 SDK for Java.

Getting started

The SCIM 2 SDK requires Java 7 and higher.

To include the SCIM 2 SDK in your project, we recommend that you use a dependency management system such as Maven or Gradle and include one of the SCIM 2 SDK components. The SCIM 2 SDK is published as four components to Maven Central:

Component Description
scim2-sdk-common Shared model, exception, and utility classes.
scim2-sdk-client The SCIM 2 SDK client API. Includes scim2-sdk-common.
scim2-sdk-server Classes for use by SCIM 2 service providers, not of interest to client developers.

Example Maven dependency block:

<dependency>
  <groupId>com.unboundid.product.scim2</groupId>
  <artifactId>scim2-sdk-client</artifactId>
  <version>2.1.1</version>
</dependency>

Example Gradle configuration:

apply plugin: 'java'

repositories {
  mavenCentral()
}

dependencies {
  compile 'com.unboundid.product.scim2:scim2-sdk-client:2.1.1'
}

Since the SCIM 2 SDK is updated regularly, be sure to check Maven Central for the latest version.

ScimService

The ScimService class is the entry point for SCIM 2 SDK client code. This class is built around the JAX-RS Client interface. To construct a ScimService instance, you must first create a WebTarget instance from the Data Governance Broker’s base SCIM URI.

Client restClient = ClientBuilder.newClient();
WebTarget target =
    restClient.target(new URI("https://example.com/scim/v2"));
ScimService scimService = new ScimService(target);

We actually need to do a little bit more, because we need to configure the Client instance to make requests using an access token. There are many ways we can do this, but one of the simplest ways is to include the org.glassfish.jersey.security:oauth2-client dependency and to register the access token using the OAuth2ClientSupport class.

final String bearerToken = "...";
ClientConfig config = new ClientConfig();
Client restClient = ClientBuilder.newClient(config)
    .register(OAuth2ClientSupport.feature(bearerToken));
WebTarget target =
    restClient.target(new URI("https://example.com/scim/v2"));
ScimService scimService = new ScimService(target);

In a moment, we’ll go over how to make requests, but first, we need to learn about the objects that are returned when we make requests with ScimService.

SCIM resource classes

A ScimService instance’s various request methods return objects that implement the ScimResource interface. These will either be of type GenericScimResource, or they will be subclasses of BaseScimResource. You choose the return type, so understanding the difference is crucial.

BaseScimResource

BaseScimResource is an abstract base class from which you can derive POJO model classes representing SCIM resource types. Since these classes usually consist of simple getters and setters, working with them is simple, but you need to make your own. It’s generally a good idea to do this for any custom resource types that will be used in your deployment.

A good example of a BaseScimResource subclass is the UserResource class in com.unboundid.scim2.common.types.

GenericScimResource

GenericScimResource is a powerful and versatile wrapper around the Jackson Databind API, which exposes a SCIM resource as a JSON node. Unlike BaseScimResource subclasses, which are custom-built for specific resource types, GenericScimResource objects may represent any resource type. Its methods are correspondingly more generic.

Most GenericScimResource methods take a special kind of object called Path, which acts as a selector for a specific node in the resource’s JSON tree. The GenericScimResource class is most often used in conjunction with the SCIM 2 SDK’s JsonUtils class, which contains a few very useful methods for converting back and forth between serializable Java objects and Jackson JsonNode objects.

Making requests

In this article, we won’t cover every request type. Instead, we’ll demonstrate how GET requests are performed using the SCIM 2 SDK. While doing so, we’ll see some patterns that apply to other kinds of requests made with the SCIM 2 SDK.

First, we can retrieve a resource by URI.

GenericScimResource scimUser =
  scimService.retrieve(ScimService.ME_URI, GenericScimResource.class);

If we know a resource’s resource type endpoint and ID, then we can use those instead of a URI.

GenericScimResource scimUser =
  scimService.retrieve("Users", "2819c223-7f76-453a-919d-413861904646",
  GenericScimResource.class);

If we need more control over the request, then we can use a different method, retrieveRequest(...). This method returns a ResourceRequestBuilder, which exposes a fluent API for modifying the request. The invoke(...) method builds and submits the request.

GenericScimResource scimUser =
  scimService.retrieveRequest("Users", "2819c223-7f76-453a-919d-413861904646")
  .header("X-Cat-Food", "Meow Mix")
  .queryParam("gorilla", "Harambe")
  .attributes("userName", "emails")
  .invoke(GenericScimResource.class);

Methods for the other requests types are also available that similarly return RequestBuilder objects for modifying the request.

A commonality you’ll have noticed between the above request examples is that the GenericScimResource class was provided when making the request, and an instance of the same was returned. A derivative of BaseScimResource could also have been used. This flexibility lets you choose the resource class that works best for you.

Further information

In the following articles, we’ll show more examples of using the SCIM 2 SDK. You can also refer to the following sources: