UnboundID SCIM 2 SDK 5.0.0

We have just released version 5.0.0 of the UnboundID SCIM 2 SDK. It is available for download from GitHub and the Maven Central Repository. This release includes the following changes:

• The UnboundID SCIM 2 SDK is now available under the terms of the Apache License, Version 2.0, which is a very permissive OSI-approved open source license. This is intended to offer better compatibility with other Ping Identity software that is already available under the Apache License. In comparison to the existing support for the GNU GPLv2 and LGPLv2.1, the Apache License imposes fewer restrictions on how you can use the SCIM SDK, and we hope that this will make it easier to use in your applications, whether open source or proprietary. For legacy compatibility, the SCIM SDK is still available under the terms of the GPLv2, LGPLv2.1, and UnboundID Free Use licenses, but we recommend that new users consider using it under the Apache License. For more information regarding licensing, see LICENSE.md.

• The SCIM 2.0 standard was updated in October 2025 with support for cursor-based pagination, which is defined in RFC 9865. Cursor-based pagination is an alternate type of API pagination that uses string cursor identifiers instead of page numbers, which allows SCIM services to offer an alternative means of returning more results. This update includes new helper methods, exception types, documentation, and updates to existing classes that now interface with cursors. Note that these updates are backward compatible with older releases of the SCIM SDK, so there are no changes required for applications that do not require cursor-based pagination. For more background, see the documentation for the new PaginationConfig class, the ListResponse class, and the RFC itself.

• Removed the ListResponse(java.util.Map) constructor, as well as the BaseScimResource#addExtensionValue methods. These were deprecated in 4.1.0.

• Updated date-time translation of data during serialization and deserialization. Previously, the SCIM SDK relied on the Jakarta XML Binding API (also known as JAX-B) in scim2-sdk-common for this purpose, but it now uses libraries supplied directly by Java SE. As a result, scim2-sdk-common no longer contains the JAX-B dependency and only has dependencies on Jackson libraries. A new DateTimeUtils.parse(long) method has been added, but the interface of the DateTimeUtils class has remained unchanged otherwise. Existing projects that upgrade to this version of the SCIM SDK should not require any changes.

• Added a new ServiceProviderConfigResource() constructor that accepts a varargs parameter for AuthenticationScheme objects, allowing them to be passed in directly. This allows callers to avoid the extra step of wrapping these objects in a list.

• (#269) Updated the definition of the Member class so that $ref is no longer a required attribute, since it is similar to the value parameter and is sometimes set to null in practice.

• (#272) Fixed an issue with SearchRequestBuilder where it was possible for the parser to hang if a list response contained undefined attributes.

• Updated remove patch operations to validate paths when objects are created. This change is specific to non-standard remove operations that set a value field for group membership updates, and does not affect most patch operations. This type of remove operation was added in 4.0.0, but paths were validated when operations were applied (i.e., paths were only validated when trying to update a SCIM resource).

• Updated the following dependencies:

  • Jackson: 2.19.2 -> 2.20.0
  • Jersey: 3.1.10 -> 3.1.11

UnboundID SCIM 2 SDK 4.1.1

We have just released version 4.1.1 of the UnboundID SCIM 2 SDK. It is available for download from GitHub and the Maven Central Repository. This release includes one minor change regarding non-standard remove PATCH operations:

• Updated remove patch operations to validate paths when objects are created. This change is specific to non-standard remove operations that set a value field for group membership updates, and does not affect most patch operations. This type of remove operation was added in 4.0.0, but paths were validated when operations were applied (i.e., paths were only validated when trying to update a SCIM resource).

UnboundID SCIM 2 SDK 4.1.0

We have just released version 4.1.0 of the UnboundID SCIM 2 SDK. It is available for download from GitHub and the Maven Central Repository. This release includes the following changes:

• Deprecated the BaseScimResource.addExtensionValue() methods. These methods allowed creating schema extension attributes whose values are arrays instead of objects, which is a form that is not used in practice. Thus, these methods will be removed in a future release.

• (#261) Fixed ClassCastException errors after deserializing a ListResponse. This specifically occurred if an application tried to use fields stored in the Resources array without the use of scim2-sdk-client. Now, the SCIM SDK supports these conversions (via Jackson TypeReference objects). See the class-level Javadoc of ListResponse for more information. As a result of this change, the map-based constructor, ListResponse(java.util.Map), is now deprecated and will be removed in a future release.

• Simplified integration with the scim2-sdk-client library. When sending Java objects as JSON payloads, the RequestBuilder subclasses now use GenericScimResource objects. This effectively means that the SCIM SDK now takes responsibility for converting Java objects to an ObjectNode before sending requests. This eliminates the need to set certain Jackson/Jersey properties to carefully tune the JSON in a request body. If you have previously added custom HTTP configuration to your project specifically for the SCIM SDK, you may be able to remove some properties after upgrading to this version.

• (#174) Added patch operation support for group membership updates that contain a value. An example JSON for this request type is shared below:

  {
    "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
    "Operations": [{
      "op": "remove",
      "path": "members",
      "value": {
        "members": [{
          "value": "2819c223-7f76-453a-919d-413861904646"
        }]
      }
    }]
  }

  RFC 7644 states that remove operations have an op and a path, but does not permit a value. Nevertheless, some SCIM services mandate the use of a value to process updates that remove a user from a group, as opposed to providing the value in a path filter. To help interface with these type of APIs, PatchOperation has been enhanced with new setRemoveOpValue() and getRemoveMemberList() methods. For more details, see PatchOperation.setRemoveOpValue(JsonNode). Note that this request cannot be created with PatchOperation.create() for backward compatibility.

• Added a new variant of GroupResource.setMembers() that allows specifying members individually so that arguments no longer need to be wrapped in a list. Now, calls such as group.setMembers(new Member()) are possible.

• Enhanced the Path class to simplify certain usages. These include:

  • Simple attribute paths (e.g., userName) were previously created with Path.root().attribute("userName"). With this release, this can also be created with Path.of("userName"). Note that this may only be used for simple, top-level attributes that are typically hard-coded. Client paths should still utilize Path.fromString().
  • To fetch the last element in a path, library calls such as path.getElement(path.size() - 1) can now be shortened to path.getLastElement().

• Updated the documentation for the UserResource, GroupResource, and Group classes. This aimed to highlight the distinction between GroupResource and Group, and also provide examples for how these classes may be used. GroupResource represents a group object/entity, whereas a Group is a subfield on a user resource (similar to Email).

• Updated the documentation of the Path class to elaborate on the definition of an attribute path, as well as provide examples for how to interface with the class.

• Added a new ForbiddenException.sensitive() method to simplify the creation of a 403 FORBIDDEN exception for a client that has entered potentially-sensitive information via URL query parameters. This exception encourages SCIM clients to re-issue these requests as a POST search request that is less susceptible to leaking this information from web browsers or log data.

• Updated Jackson to version 2.19.2.

UnboundID SCIM 2 SDK 4.0.0

We have just released version 4.0.0 of the UnboundID SCIM 2 SDK. It is available for download from GitHub and the Maven Central Repository. This release includes the following changes:

• Removed support for Java 11. The UnboundID SCIM 2 SDK now requires Java 17 or a later release.

• (#102) Previous releases of the SCIM SDK set many classes as final to encourage applications to follow strict compliance to the SCIM standard. However, this also makes it difficult to integrate with services that do not properly follow the standard. An example of this is a SCIM error response that contains extra fields in the JSON body. To ensure this library remains useful for working with other types of SCIM services, and to help accommodate these integrations, the SCIM SDK has been updated so that several model classes are no longer final, allowing applications to extend them if needed. The following classes were updated:

  • scim2-sdk-client builder classes such as CreateRequestBuilder.java
  • ErrorResponse.java
  • GenericScimResource.java
  • ListResponse.java
  • Meta.java
  • SearchRequest.java

• (#81) Added a new property that allows ignoring unknown fields when converting JSON text to Java objects that inherit from BaseScimResource. A common problem when working with non-compliant SCIM services is when extra fields are present in the JSON, which would cause the SCIM SDK to throw JsonProcessingException errors. This new property behaves similarly to the FAIL_ON_UNKNOWN_PROPERTIES setting from the Jackson library, and allows for easier integration with SCIM service providers that include extra non-standard attributes in their responses. To enable this setting, set the following property in your application code:

  BaseScimResource.IGNORE_UNKNOWN_FIELDS = true;

• Updated the default behavior for ADD patch requests with value filters (e.g., emails[type eq "work"].display). Previously, for this example path, the SCIM SDK would always add a new email to the list of existing emails, but this is not always desired when an application wishes to target a user's existing work email. The SCIM SDK will now target existing values within the multi-valued attribute (emails in this example). If you previously had code that set this property to false, it may now be removed. For more background on this type of patch request, see the release notes for the 3.2.0 release where this was introduced (but not made the default). To restore the old behavior, set the following property in your application.

  PatchOperation.APPEND_NEW_PATCH_VALUES_PROPERTY = true;

• (#97, #150) Updated SearchRequestBuilder to be null-safe and more permissive of ListResponse JSON objects with non-standard attribute casing (e.g., if a response includes a "resources" array instead of "Resources").

• Updated the Meta class so that its setters may be chained together with the builder pattern (e.g., new Meta().setResourceType("User").setVersion("version")). A new class-level Javadoc describing this attribute has been added, and explains how the new pattern may be used.

• Fixed an issue with methods that interface with schema extensions such as BaseScimResource.getExtensionValues(String). These methods, which accepted paths as a string, previously performed updates to the extension data incorrectly.

• Added a new variant of SearchRequestBuilder.filter() that accepts a Filter object directly. This simplifies calls such as builder.filter(filterObj.toString()) to builder.filter(filterObj). If you have any calls that pass in the null keyword, they may be updated to filter((String) null) to address compilation errors.

• Created new Filter.complex() methods that will create a complex value filter. This is equivalent to the existing Filter.hasComplexValue() methods, but with a less ambiguous name. The existing hasComplexValue() methods are not deprecated and may still be used.

• Updated the filter documentation to provide more details, particularly with regard to AND, OR, and complex filters. The method Javadocs have also been updated to point to relevant classes for more information. For example, the documentation for Filter.eq() now includes a link to the EqualFilter class documentation.

• Updated the class-level documentation of SearchRequest to provide more background about how searches are performed in the SCIM standard.

• Removed the deprecated ScimDateFormat class, which utilized deprecated Jackson APIs. The DateTimeUtils class has been responsible for timestamp conversions between JSON strings and Java objects since the 2.3.0 release of the SCIM SDK.

• Simplified the implementation of the StaticUtils#toLowerCase() method. This had an optimization for Java versions before JDK 9 that was especially beneficial for the most common case of handling ASCII characters. Since JDK 9, however, the String class has been updated so that the class is backed by a byte array as opposed to a character array, so it is more optimal to use the JDK's implementation directly while handling null values.

• Updated the following dependencies:

  • Jackson: 2.18.3
  • Jakarta RS: 4.0.0
  • Jersey: 3.1.10

UnboundID SCIM 2 SDK 3.2.0

We have just released version 3.2.0 of the UnboundID SCIM 2 SDK. It is available for download from GitHub and the Maven Central Repository.

Note that the next release version is planned to be 4.0.0. Among other changes, this will increase the minimum required Java version to JDK 17, and Java 11 will no longer be supported.

This release includes the following changes:

• (#147) Added better customization of the MapperFactory. The MapperFactory class can be used to customize the behavior of the SDK when it converts JSON strings to Java Objects, and vice versa. This release now supports overriding the object mapper returned by the JsonUtils.createObjectMapper() method to allow for the addition of custom serializers and deserializers. See the class-level Javadoc of MapperFactory for more information on how to accomplish this.

• (#213) Added a property that allows ADD patch operations with value filters to target an existing value. For example, consider the following patch request. This request aims to add a display field on a user's work email.

  {
    "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
    "Operations": [
      {
        "op": "add",
        "path": "emails[type eq \"work\"].display",
        "value": "Work Email"
      }
    ]
  }

  When the new behavior is configured, this operation will search the resource for an existing "work" email and add a "display": "Work Email" field to that email. This behavior allows for better integration with SCIM provisioners that send individual requests such as emails[type eq "work"].display followed by emails[type eq "work"].value, which are intended to target the same email. To use this behavior, toggle the property by adding the following Java code in your application:

  PatchOperation.APPEND_NEW_PATCH_VALUES_PROPERTY = false;

  The default value of APPEND_NEW_PATCH_VALUES_PROPERTY is true, which will always add a new value (i.e., email) on the multi-valued attribute instead of updating an existing value/email. This matches the behavior of the SDK since the 3.0.0 release.

• Refreshed the documentation of the GenericScimResource class to provide better insight on how it can be used to define resource types for objects that don't have a strongly defined schema. The class-level Javadoc describes how to interface with the object effectively, and the methods now provide clearer examples of how they can be used.

• (#233) Updated the ListResponse class to prevent deserialization errors when the Resources array is null. This is now permitted when totalResults and/or itemsPerPage is set to 0. RFC 7644 Section 3.4.2 explicitly states that the Resources array may be null when totalResults is 0, so the SCIM SDK will no longer throw deserialization exceptions when processing JSON of this form.

• Updated the class-level documentation of ListResponse to provide more background about the resource type and how to interface with the object.

• Fixed an issue where AndFilter.equals() and OrFilter.equals() could incorrectly evaluate to true.

• Updated Jackson dependencies to version 2.17.2.

UnboundID SCIM 2 SDK 3.1.0

We have just released version 3.1.0 of the UnboundID SCIM 2 SDK. It is available for download from GitHub and the Maven Central Repository. This release includes the following changes:

• Updated all classes within the UnboundID SCIM 2 SDK to utilize @Nullable and @NotNull annotations for all non-primitive input parameters, member variables, and return values. These annotations are designed to assist with the following:

  • Help provide insight when invoking SCIM SDK library methods
  • Help interface with languages like Kotlin (which has built-in null types for variables)
  • Help applications become less prone to nullability errors.

  Furthermore, the annotations will also appear in the Javadocs. This reflects a similar pattern used by the UnboundID LDAP SDK for Java, though the fully-qualified class names of the annotations are different since they take the form of com.unboundid.scim2.common.annotations.Nullable. For more information on leveraging IDE analysis with these annotations, view the README.

• Resolved an issue with replace operations that set the value field to an empty array. For example:

  {
    "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
    "Operations": [
      {
        "op": "replace",
        "path": "emails[type eq \"work\"]",
        "value": []
      }
    ]
  }

  When these operations are applied, the SCIM SDK now deletes all matching values of the targeted multi-valued attribute. If the path of the replace operation does not have a filter (type eq "work" in the example above), then the multi-valued attribute will be deleted from the resource.

UnboundID SCIM 2 SDK 3.0.0

We have just released version 3.0.0 of the UnboundID SCIM 2 SDK. It is available for download from GitHub and the Maven Central Repository. This release includes the following changes:

• Removed support for Java 8. The UnboundID SCIM 2 SDK now requires Java 11 or a later release.

• Migrated javax.* namespaces to use Jakarta EE. Since Oracle has given stewardship of the Java EE project to Eclipse, this change facilitates the usage of these libraries under the Jakarta name, which provides better integration with projects such as Spring Boot 3.0. If your project uses components from JAX-RS or Jersey related to the SCIM SDK, then these references must be updated to match the new method definitions. For example, any code that creates a javax.ws.rs.client.WebTarget before passing it to the SCIM SDK will need to provide a jakarta.ws.rs.client.WebTarget instead. To support this change, the following project dependencies were also upgraded:

  • Updated javax.xml.bind-api to jakarta.xml.bind-api version 4.0.
  • Updated javax.ws.rs-api to jakarta.ws.rs-api version 3.1.0
  • Updated javax.annotation-api to jakarta.annotation-api version 2.1.1
  • Updated Jersey from 2.39.1 to 3.1.3

• Overhauled many of the class-level Javadocs in the scim2-sdk-common package. This provides better descriptions for SCIM entities, SDK-specific constructs (e.g., ScimResource), and more background on SCIM conventions such as filtering. The new documentation also provides better descriptions for how certain classes in the SDK should be used, such as the Filter class.

• Added new constructors for some exception types involving the scimType field. This field is empty in many cases, so these new constructors set the scimType value to be null with the goal of simplifying the process of creating exceptions.

• Added support for patch operations of type ADD that contain a value selection filter in the path, e.g.,
  emails[type eq "work"].value. This type of request is used by some SCIM service providers to append extra data for multi-valued attributes such as emails or addresses.

• Removed deprecated methods in PatchOperation.java and GenericScimResource.java that utilized multi-valued boolean arrays.

SCIM 2 SDK 2.4.0

We have just released version 2.4.0 of the UnboundID SCIM 2 SDK. It is available for download from GitHub and the Maven Central Repository. This release includes the following changes:

• Fixed an issue with PatchOperations that prevented setting the value field to an empty array. The constructor would previously reject this kind of operation with a BadRequestException.

• Added a variety of methods for providing multi-valued parameters without needing to wrap the arguments into a List. For example, setting a single email on a UserResource used to be done with user.setEmails(Collections.singletonList(email)), but this can now be shortened to user.setEmails(email). Note that the existing methods are still available and have not been deprecated. Other examples include BaseScimResource.setSchemaUrns(), GenericScimResource.addStringValues(), PatchOperation.addDoubleValues(), and the PatchRequest constructor.

• Updated the schema URNs field of BaseScimResource to use a LinkedHashSet instead of a generic HashSet. This allows for a SCIM resource with multiple schema URNs to have a predictable order when the resource is deserialized into JSON.

• Deprecated methods of the form addBooleanValues() and getBooleanValueList() on the GenericScimResource and PatchOperation classes. These methods provided an interface for so-called "multi-valued boolean arrays", but boolean data is always single-valued in nature. Updating a boolean value should always be done with a replace operation type rather than an add.

• Fixed an issue where AttributeDefinition.toString() would not print the mutability of an attribute.

• Added a type field to the Member class as defined by RFC 7643 section 8.7.1.

• Fixed an issue with the attribute definitions of the members field of a GroupResource. The attribute definitions now indicate that the sub-attributes of members are all immutable.

• Fixed an issue where calling ObjectMapper.copy() would fail for object mappers that were created with JsonUtils.createObjectMapper().

SCIM 2 SDK 2.3.8

We have just released version 2.3.8 of the UnboundID SCIM 2 SDK. It is available for download from GitHub and the Maven Central Repository. This release includes the following changes:

• Updated the deserialized form of ListResponse objects so that the itemsPerPage and startIndex fields are listed at the top with totalResults. This matches the form of ListResponses shown in RFC 7644.
• Updated the PatchOperation class to accept operation types where the first letter is capitalized, e.g., "Add". This makes the SDK more permissive of operation types that violate RFC 7644, which is a known problem with Azure Active Directory as a SCIM client.
• Updated the Jackson and jackson-databind dependencies to 2.14.2.
• Updated the jersey dependency to 2.39.1 to address a ClassCastException error.

SCIM 2 SDK 2.3.7

Changes In This Release

• Added ParserOptions class, which may be used to extend the set of characters allowed in filtered
  attribute names.
• Updated the TestNG dependency to 7.4.0 and corrected its scope from the default 'compile' to 'test'.