Skip to content

Update README and public docs. #290

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kqarryzada wants to merge 2 commits into
base: master
Choose a base branch
from
+156 −77
Open

Update README and public docs. #290

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
80718be
Update public docs.
kqarryzada Apr 10, 2026
20f0af5
Small edits
kqarryzada Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/bug_report.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,5 +18,5 @@ A clear and concise description of what you expected to happen.

**Additional context**
Add any other context about the problem here. For example:
- Java version: [e.g. Java 8]
- SCIM 2 SDK version: [e.g. 2.3.7, master branch]
- Java version: [e.g., Java 25]
- SCIM 2 SDK version: [e.g., 5.0.0, master branch]
8 changes: 7 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,13 @@ Thanks for taking the time to contribute!

#### Before submitting a bug report

It can be helpful to review the documentation and examples, including the [Javadocs](https://javadoc.io/doc/com.unboundid.product.scim2/scim2-parent/) and the [wiki](https://github.com/pingidentity/scim2/wiki). It's also a good idea to search the [issue tracker](https://github.com/pingidentity/scim2/issues) to see if your issue or one similar to it has already been reported.
It can be helpful to review the documentation and examples. Please check the following before opening an issue:
* Read through the [FAQ](https://github.com/pingidentity/scim2/wiki/Common-Problems-and-FAQ) to check if your issue or
question has already been addressed.
* Check the [Javadocs](https://javadoc.io/doc/com.unboundid.product.scim2/scim2-parent/) and the
[wiki](https://github.com/pingidentity/scim2/wiki) to ensure the behavior is likely not intentional.
* It's also a good idea to search the [issue tracker](https://github.com/pingidentity/scim2/issues) to see if your issue
or one similar to it has already been reported.

#### How do I submit a bug report?

Expand Down
218 changes: 145 additions & 73 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,53 +3,98 @@
[![Build Status](https://github.com/pingidentity/scim2/actions/workflows/build-and-test.yaml/badge.svg)](https://github.com/pingidentity/scim2/actions/workflows/build-and-test.yaml)

# UnboundID SCIM 2 SDK for Java
The UnboundID SCIM 2 SDK for Java provides a powerful and flexible set of APIs that helps developers
create applications that interface with the SCIM protocol. This SDK contains a foundation for
building both client and server applications, and contains support for managing sensitive user data,
filtering, request handling, generating error responses, and more. It is completely free and open
source, and is developed by [Ping Identity Corporation](https://www.pingidentity.com/).


## What is SCIM?
[SCIM](https://www.simplecloud.info), or _System for Cross-domain Identity Management_, is an IETF
standard that defines an extensible schema mechanism and REST API for **managing users and other
identity data**. SCIM is used by a variety of vendors — including GitHub, Salesforce, Microsoft,
identity data**. SCIM is used by a variety of vendors — including Salesforce, Microsoft,
Cisco, Sailpoint, and Ping Identity — for a variety of purposes, including user provisioning,
directory services, attribute exchange, and more.

The UnboundID SCIM 2 SDK for Java provides a powerful and flexible set of APIs for interacting with SCIM service providers and resources. Use it to build applications and servers that interoperate with SCIM servers such as the [PingDirectory Server](https://www.pingidentity.com/en/platform/capabilities/directory.html).

The SCIM 2 SDK consists of the following components:

| Component name | What it is | Who needs it |
| --- | --- | --- |
| `scim2-sdk-client` | The SCIM 2 client API. | SCIM client developers. |
| `scim2-ubid-extensions` | Model classes representing UnboundID extensions to the SCIM standard. This component is subject to API changes and should be considered experimental. | SCIM client developers using features specific to UnboundID servers. |
| `scim2-sdk-server` | Classes for use by SCIM 2 service providers. | SCIM service provider implementers. |
| `scim2-sdk-common` | Shared model, exception, and utility classes. | Included as a transitive dependency of all of the above. |

# How to get it
The SCIM 2 SDK is available from Maven Central and can be included in your product like any other Maven dependency. Check Maven Central for the latest available version of SCIM 2 SDK dependencies.

For general-purpose clients:

SCIM is an open standard that is interoperable, which means that SCIM clients should be able to
communicate with any SCIM 2-based service. This avoids the need to accommodate multiple APIs to
communicate with different platforms, and also avoids vendor lock-in concerns. In practice,
different SCIM services can have variance by enforcing their own constraints, but still provide much
common ground.

## Advantages of the UnboundID SCIM 2 SDK
The UnboundID SCIM 2 SDK provides many strong benefits for applications that need to communicate
with SCIM 2.0 clients or servers:

* Full support for the SCIM 2.0 protocol as defined by the latest specification. This includes
support for PATCH operations, filter processing, bulk operations, and cursor-based pagination.
* A simple and intuitive Jackson-based API that facilitates SCIM workflows, minimizing the amount
of code you need to write for tasks such as performing CRUD operations on resources.
* `@NotNull` and `@Nullable` annotations are documented for all library input parameters, member
variables, and method return values. This explicitly documents nullity expectations to reduce the
likelihood of NullPointerExceptions in your code.
* Helpful model classes that allow you to interact with any SCIM resource as a Java object. This
includes a powerful interface for manipulating
[generic JSON data](https://javadoc.io/doc/com.unboundid.product.scim2/scim2-parent/latest/com/unboundid/scim2/common/GenericScimResource.html),
even when there is not a clear model class or strong schema.
* An extendable framework that allows defining custom resource types by
[extending core model classes](https://github.com/pingidentity/scim2/wiki/Common-Problems-and-FAQ#scim-service-provider-has-special-users).
* Extensive [documentation](https://javadoc.io/doc/com.unboundid.product.scim2/scim2-parent/latest/index.html)
that thoroughly explains SCIM concepts and semantics, such as
[service provider configuration](https://javadoc.io/doc/com.unboundid.product.scim2/scim2-parent/latest/com/unboundid/scim2/common/types/ServiceProviderConfigResource.html)
and [bulk requests](https://javadoc.io/doc/com.unboundid.product.scim2/scim2-parent/latest/com/unboundid/scim2/common/bulk/BulkRequest.html).
* As with other Java libraries, this SDK can be used in projects written in other JVM languages such
as Kotlin and Scala.
* Full support for interacting with Ping Identity SCIM services such as the
[PingOne SCIM API](https://developer.pingidentity.com/pingone-api/platform/scim.html).

## Supported Versions
As of version 4.0.0, the UnboundID SCIM SDK requires Java SE 17 or greater.
This library also depends on the Jackson 2.x libraries for JSON serialization and deserialization.

## Structure
This library is separated into multiple modules to target specific use cases, and consists of the
following components:

| Component name | What it is | Who needs it |
|-------------------------|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `scim2-sdk-common` | This package contains core SCIM model classes, parsers, filter and PATCH processing, etc. | Developers looking for model classes, utilities, or general SCIM support. |
| `scim2-sdk-client` | This package contains classes to help create SCIM 2 client applications. | SCIM client developers using JAX-RS. |
| `scim2-sdk-server` | This package contains classes to help create SCIM 2 service providers. | SCIM service developers using JAX-RS. Spring libraries should use `common`. |
| `scim2-ubid-extensions` | This package contains classes representing Ping Identity extensions to the SCIM standard. | Developers using features specific to Ping Identity services. |
| `scim2-parent` | This package contains all of the dependencies listed above. | Anyone who needs all of the above. |

More information on each section:
* `scim2-sdk-common`: This package contains the core SCIM constructs and utility classes. This
contains logic for SCIM filtering, performing updates/searches on JSON data, bulk request
processing, and more. It may be used standalone without the other components.
* `scim2-sdk-client`: This component helps create SCIM 2 client applications using JAX-RS.
For more information, see the [wiki](https://github.com/pingidentity/scim2/wiki/JAX-RS-Client-examples).
* `scim2-sdk-server`: This component helps create SCIM 2 services using JAX-RS. If you are not using
JAX-RS and are using another solution (e.g., Spring), the `scim2-sdk-common` component is
generally a better choice and may be used directly.
* `scim2-ubid-extensions`: Provides model classes specific to Ping Identity based constructs and
SCIM extensions. This component is subject to API changes and should be considered experimental.
* `scim2-parent`: The parent module for all of the other components.

## How to get it
The UnboundID SCIM SDK is available from Maven Central and can be included in your product like any other
Maven dependency. Check Maven Central for the latest available versions.
```xml
<dependency>
<groupId>com.unboundid.product.scim2</groupId>
<artifactId>scim2-sdk-client</artifactId>
<version>VERSION</version>
<artifactId>scim2-sdk-common</artifactId>
<version>${scim2.sdk.version}</version>
</dependency>
```

For clients using UnboundID-specific features:
You may also download SCIM SDK builds from the [Releases](https://github.com/pingidentity/scim2/releases) page.

```xml
<dependency>
<groupId>com.unboundid.product.scim2</groupId>
<artifactId>scim2-ubid-extensions</artifactId>
<version>VERSION</version>
</dependency>
```

You may also download SCIM 2 SDK builds from the [Releases](https://github.com/pingidentity/scim2/releases) page.

# How to use it
As of version 4.0.0, the UnboundID SCIM 2 SDK requires Java SE 17 or greater.
As of version 3.0.0, the UnboundID SCIM 2 SDK requires Java SE 11 or greater.

The primary point of entry for a client is the `ScimService` class, which represents a SCIM service provider, such as the PingDirectory Server. This class acts as a wrapper for a [JAX-RS](https://github.com/jax-rs) client instance, providing methods for building and making requests.
## How to use it
The primary point of entry for a client is the `ScimService` class, which represents a SCIM service
provider. This class acts as a wrapper for a [JAX-RS](https://projects.eclipse.org/projects/ee4j.rest)
client instance, providing methods for building and making requests.

Other classes provide facilities for selecting attributes by path, building query filters, and working with JSON documents. SCIM resources returned from a service provider can either be represented as POJOs or using an API based on the [Jackson](https://github.com/FasterXML/jackson-docs) tree model.

Expand All @@ -63,74 +108,101 @@ import com.unboundid.scim2.common.GenericScimResource;
import com.unboundid.scim2.common.messages.ListResponse;
import com.unboundid.scim2.common.filters.Filter;

// Create a ScimService
Client client = ClientBuilder.newClient().register(OAuth2ClientSupport.feature("..bearerToken.."));
// Create a ScimService.
Client client = ClientBuilder.newClient()
.register(OAuth2ClientSupport.feature("..bearerToken.."));
WebTarget target = client.target("https://example.com/scim/v2");
ScimService scimService = new ScimService(target);

// Create a user
UserResource user = new UserResource();
user.setUserName("babs");
user.setPassword("secret");
Name name = new Name()
.setGivenName("Barbara")
.setFamilyName("Jensen");
user.setName(name);
Email email = new Email()
.setType("home")
.setPrimary(true)
.setValue("babs@example.com");
user.setEmails(email);
// Create a user with a POST request by calling create().
UserResource user = new UserResource()
.setUserName("babs")
.setPassword("secret");
user.setName(new Name()
.setGivenName("Barbara")
.setFamilyName("Jensen"));
user.setEmails(new Email()
.setType("home")
.setPrimary(true)
.setValue("babs@example.com"));
user = scimService.create("Users", user);

// Retrieve the user as a UserResource and replace with a modified instance using PUT
// Retrieve the latest version of the user as a UserResource, and
// update/replace it with a PUT request.
user = scimService.retrieve("Users", user.getId(), UserResource.class);
user.setDisplayName("Babs");
user = scimService.replace(user);

// Retrieve the user as a GenericScimResource and replace with a modified instance using PUT
// Retrieve the user as a GenericScimResource and update/replace it with a PUT
// request.
GenericScimResource genericUser =
scimService.retrieve("Users", user.getId(), GenericScimResource.class);
genericUser.replace("displayName", "Babs Jensen");
genericUser = scimService.replaceRequest(genericUser).invoke();

// Perform a partial modification of the user using PATCH
// Perform a partial modification of the user with a PATCH request.
scimService.modifyRequest("Users", user.getId())
.replaceValue("displayName", "Babs")
.invoke(GenericScimResource.class);
.replaceValue("displayName", "Babs")
.invoke(GenericScimResource.class);

// Perform a password change using PATCH
// Perform a password change with a PATCH request.
scimService.modifyRequest("Users", user.getId())
.replaceValue("password", "new-password")
.invoke(GenericScimResource.class);
.replaceValue("password", "new-password")
.invoke(GenericScimResource.class);

// Search for users with the same last name as our user
// Search for users with the same last name as our user. Fetch the first page
// of results, which should have a maximum of five resources on the page. The
// service should only return the value of the "name" attribute.
ListResponse<UserResource> searchResponse =
scimService.searchRequest("Users")
scimService.searchRequest("Users")
.filter(Filter.eq("name.familyName", user.getName().getFamilyName()))
.page(1, 5)
.attributes("name")
.invoke(UserResource.class);
```

For detailed information about using the SCIM 2 SDK, including more examples, please see the [wiki](https://github.com/pingidentity/scim2/wiki).
For detailed information about using the UnboundID SCIM SDK, including more examples, please see the
[wiki](https://github.com/pingidentity/scim2/wiki).

# Nullability Annotations
As of version 3.1.0, the SCIM 2 SDK provides the `com.unboundid.scim2.common.annotations.Nullable`
and `com.unboundid.scim2.common.annotations.NotNull` annotations for all input parameters, member
variables, and method return values. This is designed to provide insight when invoking SCIM SDK
## Building
This project is built with Maven. To build the source code contained in this repository, run:
```
# Linux or Mac
./mvnw clean package

# Windows:
mvnw.cmd clean package
```
If desired, the code styling rules enforced by Checkstyle can be ignored with the
`-Dcheckstyle.skip=true` flag.

## Nullability Annotations
As stated above, all inputs, member variables, and return values in this library are labelled with
`com.unboundid.scim2.common.annotations.Nullable` and `com.unboundid.scim2.common.annotations.NotNull`
annotations. To showcase an example, the following method in the `UserResource.java` class accepts
`null` username values, and will never return a `null` object:
```java
@NotNull
public UserResource setUserName(@Nullable final String userName);
```
These annotations can be seen in the Javadocs. This aims to provide insight when invoking SCIM SDK
library methods, help interface with languages like Kotlin (which has built-in null types for
variables), and to help applications become less prone to nullability problems. These annotations
can be leveraged by IDE tools to help validate objects that are given to and received from the SCIM
SDK library. To configure/integrate this into your environment, view the documentation of your IDE
of choice. Some popular choices are linked below:
* [IntelliJ IDEA](https://www.jetbrains.com/help/idea/annotating-source-code.html#configure-nullability-annotations)
* [Eclipse](https://help.eclipse.org/latest/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Ftasks%2Ftask-using_null_annotations.htm)


# Reporting issues
of choice (e.g., [IntelliJ IDEA](https://www.jetbrains.com/help/idea/annotating-source-code.html#configure-nullability-annotations),
[Eclipse](https://help.eclipse.org/latest/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Ftasks%2Ftask-using_null_annotations.htm)).

## Reporting issues
Please report bug reports and enhancement requests through this project's [issue tracker](https://github.com/pingidentity/scim2/issues). See the [contribution guidelines](CONTRIBUTING.md) for more information.
Note that Ping Identity does not accept third-party code contributions.

## License
As of the 5.0.0 release, the UnboundID SCIM SDK is available under the terms of the following
licenses:
* The [Apache License, version 2.0](LICENSE.md) (recommended).
* The GNU General Public License version 2 ([GPLv2](resource/LICENSE-GPLv2.txt))
* The GNU Lesser General Public License version 2.1 ([LGPLv2.1](resource/LICENSE-LGPLv2.1.txt))
* The legacy [UnboundID Free Use License](resource/LICENSE-UnboundID-SCIM2.txt)

# License
The UnboundID SCIM2 SDK is available under the following licenses: the Apache License version 2.0, the GNU General Public License version 2 (GPLv2), the GNU Lesser General Public License version 2.1 (LGPLv2.1), and a free-right-to-use license created by UnboundID Corp. See the [LICENSE](LICENSE.md) file for more info.
For further background on project licensing, see the [LICENSE.md](LICENSE.md) file.
3 changes: 2 additions & 1 deletion scim2-ubid-extensions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ This component contains model classes representing UnboundID-proprietary extensi

## About the SCIM 2 SDK

The UnboundID SCIM 2 SDK for Java provides a powerful and flexible set of APIs for interacting with SCIM service providers and resources. Use it to build applications and servers that interoperate with SCIM servers such as the [UnboundID Data Broker](https://www.unboundid.com/data-broker).
The UnboundID SCIM 2 SDK for Java provides a powerful and flexible set of APIs for interacting with SCIM service providers and resources. Use it to build applications and servers that interoperate with SCIM services such as the
[Ping Identity Directory Server](https://docs.pingidentity.com/pingdirectory/latest/pd_ds_landing_page.html).

Please refer to the [SCIM 2 SDK README](https://github.com/pingidentity/scim2) for license and support information.
Loading