diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 1c1b9f73..a8dbfbf6 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -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] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ec87b8da..1b7b8598 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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? diff --git a/README.md b/README.md index e4913e47..8a1ff9b2 100644 --- a/README.md +++ b/README.md @@ -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 com.unboundid.product.scim2 - scim2-sdk-client - VERSION + scim2-sdk-common + ${scim2.sdk.version} ``` -For clients using UnboundID-specific features: +You may also download SCIM SDK builds from the [Releases](https://github.com/pingidentity/scim2/releases) page. -```xml - - com.unboundid.product.scim2 - scim2-ubid-extensions - VERSION - -``` - -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. @@ -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 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. diff --git a/scim2-ubid-extensions/README.md b/scim2-ubid-extensions/README.md index 3bac570d..8bdc1c4c 100644 --- a/scim2-ubid-extensions/README.md +++ b/scim2-ubid-extensions/README.md @@ -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.