All notable changes to this project will be documented in this file. This project adheres to Semantic Versioning.
Added support for bulk operations, requests, and responses as defined by the SCIM standard. To get
started with implementing bulk request support for client or server applications, see the
documentation in the BulkRequest.java class, which provides a comprehensive overview of how bulk
operations are defined and utilized in the SCIM standard. It also includes notes on how to interface
with the new classes, general structures for handling bulk data, useful utility methods, and more.
Updated Jackson to 2.21.2.
Updated ErrorResponse.java to print attributes in an order that is more consistent with the
example JSON objects presented in RFC 7644. Now, status is the last attribute printed.
Added new ContentTooLargeException and RateLimitException classes corresponding to the HTTP 413
and HTTP 429 status codes.
Added new status() and statusInt() method to all exception types. For example, to obtain a
string of "400" corresponding to 400 BAD REQUEST, use BadRequestException.status().
Simplified patch processing by adding applyToResource() on the PatchRequest and PatchOperation
classes. These are an improvement over the existing apply() variants, which require passing in
ObjectNode or GenericScimResource instances. Conversely, the new methods accept any ScimResource
object, which is useful since SCIM patch updates almost always target a SCIM resource. For example:
// Before:
UserResource user = getUser();
GenericScimResource genericUser = user.asGenericScimResource();
patchRequest.apply(genericUser);
UserResource updatedUser =
JsonUtils.nodeToValue(genericUser.getObjectNode(), UserResource.class);
// New in 5.1.0:
UserResource user = getUser();
UserResource updatedUser = patchRequest.applyToResource(user);
The existing apply() methods are not deprecated and may still be used.
Added a system property that can use the UTC timezone when converting ISO timestamps from JSON data
into Calendar objects. The "GMT+00:00" timezone is still the default. The value may also be updated
directly via the public DateTimeUtils.USE_GMT_CALENDARS variable. Note that existing properties,
BaseScimResource.IGNORE_UNKOWN_FIELDS and PatchOperation.APPEND_NEW_PATCH_VALUES_PROPERTY,
have been updated so that they can be toggled by a Java system property as well. This allows
changing these values without requiring a code change. Note that if the system property value is
changed at runtime, a restart is required for the change to take effect.
Deprecated the com.unboundid.scim2.server.PATCH annotation class. At the time this class was
written, JAX-RS did not support a PATCH annotation like it did for other HTTP methods. Now, the
jakarta.ws.rs.PATCH is a better choice that should be used instead.
Deprecated getters and setters in the MapperFactory.java class. In the upcoming Jackson 3 release,
many of the referenced classes (e.g., SerializationFeature.java) have been renamed. The
MapperFactory now supports an alternate scheme for adding customizations with the createBuilder()
method. This provides access to a JsonMapper.Builder object that can directly take customizations.
If your application does not make customizations to the SCIM SDK's object mapper instance, then
there is no change required. See the class-level documentation of MapperFactory for more info.
For consistency with other open source Ping Identity software, the UnboundID SCIM 2 SDK for Java is now available under the terms of the Apache License (version 2.0). For legacy compatibility, the SCIM SDK is still available under the terms of the GPL v2, LGPL v2.1, and UnboundID Free Use licenses.
Removed the ListResponse(java.util.Map) constructor, as well as the
BaseScimResource#addExtensionValue methods. These were deprecated in 4.1.0.
Updated the following dependencies:
- Jackson: 2.19.2 -> 2.20.0
- Jersey: 3.1.10 -> 3.1.11
Removed the "Jakarta XML Binding API" dependency (also known as JAX-B) from scim2-sdk-common. Now,
the common library's only dependency is Jackson. jakarta.xml.bind-api was previously used for
timestamp conversions during serialization and deserialization, but the SCIM SDK has been updated to
rely on libraries provided with Java SE instead. A new DateTimeUtils.parse(long) method has been
added, but the API of the DateTimeUtils class has remained unchanged otherwise. Existing projects
that upgrade to this version of the library should not require any changes.
Updated the definition of the Member class so that $ref is no longer a required attribute,
since it is a reflection of the value parameter and is sometimes set to null in practice.
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. Previously, paths were
only validated when operations were applied. This behavior is specific to non-standard remove
operations that set a value field, and does not affect most patch operations.
Added support for RFC 9865, which is an update to
the SCIM 2 standard that defines an alternate cursor-based type of API pagination. This allows SCIM
services to offer an alternative means of returning more results, which is ideal for services that
cannot feasibly implement index-style pagination. 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 API calls, 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.
Added new methods to the Path class to simplify certain usages and make interaction, especially instantiation, less verbose. These include:
- Creation of simple attributes (e.g.,
username) previously had to be performed withPath.root().attribute("userName"), but can now be done withPath.of("userName"). Note that this may only be used for simple, top-level attributes that are typically hard-coded. - For fetching the last element in a path, library calls such as
path.getElement(path.size() - 1)can now be shortened topath.getLastElement().
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.
Simplified integration with the scim2-sdk-client library by updating subclasses of
RequestBuilder to always provide GenericScimResource objects for JSON payloads. In previous
releases, applications needed to use the right JSON properties in the environment so that the client
library would send proper JSON when issuing HTTP requests. This update to the client library places
the responsibility for serialization on the SCIM SDK itself, and reduces the number of HTTP client
configuration properties to set within your application. If you have added custom HTTP configuration
to your project specifically for the SCIM SDK, you may be able to remove some properties.
Updated the following dependencies:
- Jackson: 2.19.2
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.
Deprecated the BaseScimResource#addExtensionValue methods, since they allowed creating schema
extension attributes whose values are arrays instead of objects. Since this is a form that is not
used in practice, these methods will be removed in a future release.
Fixed an issue where deserialization of ListResponse objects could result in ClassCastException
errors if an application tried to use fields stored in the Resources array. 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,
com.unboundid.scim2.common.messages.ListResponse.ListResponse(java.util.Map), is now deprecated
and will be removed in a future release.
Updated documentation for GroupResource and Group to highlight the distinction between the
classes, as well as provide examples of how they may be used. GroupResource represents a group
object/entity, whereas a Group is a subfield on a user resource (like Email). The documentation
for UserResource was also updated.
Added support for non-standard group membership patch remove requests 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 do not have a value. Nevertheless, some SCIM services
mandate the use of such a field to process group membership operations. To help interface with these
type of APIs, PatchOperation has new setRemoveOpValue and getRemoveMemberList methods. This
change includes support for applying these operations, where the SCIM SDK will transform the above
request into the one shown below. For more details, see PatchOperation#setRemoveOpValue(JsonNode).
Note that this request cannot be created with PatchOperation#create for backward compatibility.
{
"schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
"Operations": [{
"op": "remove",
"path": "members[value eq \"2819c223-7f76-453a-919d-413861904646\"]"
}]
}The PatchRequest and PatchOperation classes have been updated so that they are no longer final
and may be extended if desired.
Added a new variant of GroupResource#setMembers that allows specifying members individually so
that arguments no longer need to be wrapped in a list.
Removed support for Java 11. The UnboundID SCIM 2 SDK now requires Java 17 or a later release.
Updated the following dependencies:
- Jackson: 2.18.3
- Jakarta RS: 4.0.0
- Jersey: 3.1.10
Updated the default behavior for ADD patch requests with value filters (e.g.,
emails[type eq "work"].display). The SCIM SDK will now target existing values within the
multi-valued attribute. 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;
Updated SearchRequestBuilder to be more permissive of ListResponses with non-standard attribute
casing (e.g., if a response includes a "resources" array instead of "Resources").
Updated the class-level documentation of SearchRequest to provide more background about how
searches are performed in the SCIM standard.
Added a new property that allows ignoring unknown fields when converting JSON text to Java objects
that inherit from BaseScimResource. This behaves similarly to the FAIL_ON_UNKNOWN_PROPERTIES
setting from the Jackson library, and allows for easier integration with SCIM service providers
that include additional non-standard data in their responses. To enable this setting, set the
following property in your application code:
BaseScimResource.IGNORE_UNKNOWN_FIELDS = true;
Fixed an issue with methods that interface with schema extensions such as
BaseScimResource.getExtensionValues(String). These accepted paths as a string, but previously
performed updates to the extension data incorrectly.
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.
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 violate the standard. An example of this is a SCIM error response that contains extra
fields in the JSON body. 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.javaGenericScimResource.javaListResponse.javaMeta.javaSearchRequest.java
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.
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.
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.
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.
Removed the deprecated ScimDateFormat class, which makes use of deprecated Jackson APIs. The
DateTimeUtils class has been responsible for timestamp conversions between JSON strings and Java
objects from 2.3.0 onwards.
Fixed an issue where AndFilter.equals() and OrFilter.equals() could incorrectly evaluate to
true.
Updated Jackson dependencies to 2.17.2.
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 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.
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": "apollo.j@example.com"
}
]
}When the new behavior is configured, this operation will search the resource for an existing "work"
email and add a "display": "apollo.j@example.com" 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.
Updated the class-level documentation of ListResponse to provide more background about the
resource type and how to interface with the object.
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 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 provide additional context on the nullability of certain values when working with the
SDK, and the annotations will also appear in the Javadocs. Note that the fully-qualified class names
of the annotations take the form of com.unboundid.scim2.common.annotations.Nullable.
Resolved an issue with replace operations that set the value field to an empty array. When these
operations are applied, the SCIM SDK now clears all matching values of the targeted multi-valued
attribute. If the path of the replace operation does not have a filter, then the multi-valued
attribute will be deleted from the resource.
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-apitojakarta.xml.bind-apiversion 4.0.1 - Updated
javax.ws.rs-apitojakarta.ws.rs-apiversion 3.1.0 - Updated
javax.annotation-apitojakarta.annotation-apiversion 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.
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 directly into a method 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() failed for object mappers that were created with
JsonUtils.createObjectMapper().
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.
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'.
Bump jackson-databind from 2.10.2 to 2.10.5.1.
Update the Guava dependency to 29.0-jre, which addresses latest known potential security issues.
Fix possible template variable injection within search parameters and returned resource location URLs.
[Unused release version]
Updated the jackson-databind dependency to 2.9.10, which addresses latest known potential security issues.
Updated the jackson-databind dependency to 2.9.9.3, which addresses a number of potential security issues.
The SCIM 2 DateTime handling code has been updated to rely on xsd:dateTime code provided by JAXB rather than on Jackson APIs that are deprecated as of version 2.9.x. A DateTimeUtils class has been added to perform conversions between SCIM 2 DateTime strings and Java Date and Calendar objects. The ScimDateFormat class is now deprecated and should not be used.
The Version class is no longer generated at build time for each module, and is now only generated for scim2-sdk-common. Because all other modules include scim2-sdk-common as a dependency, the Version class will continue to be available for all modules. This should eliminate duplicate class warnings when the SCIM 2 SDK is included in projects built using (for example) the Maven Shade Plugin.
A GroupResource POJO class is now provided for working with SCIM Group resources.
The ListResponse#getTotalResults() method has been updated to return a value of type int rather than long.
Changed the mutability value of the UserResource groups attribute to 'readOnly' for conformance with RFC 7643.
Updated the Jackson dependencies to 2.9.9, which addresses a potential security issue found in earlier versions of that library.
Updated the jackson-databind dependency to 2.7.9.5, which addresses a number of security issues found in earlier versions of that library.
Maven POM changes: Removed unused dependencies, declared previously implicit dependencies, declared 'test' scope as appropriate, and added a dependencyManagement section to the scim2-parent POM.
Fixed an issue with GenericScimResource.replaceValue(String, Date) wrapping date values in double quotes.
Updated ErrorResponse to serialize its "status" field as a JSON string rather than as a number for compliance with RFC 7644. Deserialization of this field is backwards compatible and will accept either a number or a string. Clients expecting the "status" field as a JSON string (including older SCIM 2 SDK clients) will need to be updated for compatibility.
Fixed several issues around binary attribute handling.
Fixed a SCIM issue to restore the use of the implicit "value" sub-attribute in filters to reference specific values of simple multi-valued attributes
Allow replacement of singular value using a value filter if the value filter uses the special-case "value" path.
Added ability to change "accept" and "content-type" headers in the SCIM client.
Fixed the handling of sub-attribute paths in the excludedAttributes parameter.
PUT requests will now replace the value of a caseExact attribute whose only change is to case.
Updated the EmailValidationRequest and TelephonyValidationRequest for compatibility with Data Governance Broker 6.0.1.0.
Changed unboundid URNs to pingidentity.
Add exception class for 405 Method Not Allowed exceptions, and corrected some exception mapping issues.
Fixed a couple filtering and search issues.
Make sure the Response is always closed after a SCIM operation.
Initial Public Release