SCIM Group API Basics
Liferay DXP 2024.Q1+/Portal GA112+
Liferay provides a headless API to perform CRUD operations on SCIM groups to keep their information in sync with your company’s applications. SCIM groups are analogous to user groups in Liferay. Use the /scim
endpoint from the API Explorer to manage SCIM groups.
Adding a Group
Start a new Liferay DXP instance by running
Sign in to Liferay at http://localhost:8080 using the email address test@liferay.com and the password test. When prompted, change the password to learn.
Once Liferay is running,
-
Download and unzip SCIM Group API Basics.
-
Use the cURL script to add a SCIM group in Liferay. On the command line, navigate to the
curl
folder. Execute theGroups_POST_ToInstance.sh
script.The JSON response shows the addition of a new SCIM group:
-
Verify this by opening the Global Menu (
), and navigating to Control Panel → Users Groups. See that a new user group has been added.
-
Alternatively, call the REST service using the Java client. Navigate into the
java
folder and compile the source files: -
Run the
Groups_POST_ToInstance
class.
Examine the cURL Command
The Groups_POST_ToInstance.sh
script calls the REST service with a cURL command.
Here are the command’s arguments:
Arguments | Description |
---|---|
"http://localhost:8080/o/scim/v1.0/v2/Groups" | The REST service endpoint |
--data-raw "{ "displayName": "Foo" }" | The data to post |
--header "Content-Type: application/scim+json" | Indicates that the request body format is in JSON and conforms to the SCIM protocol. |
--request "POST" | The HTTP method to invoke at the specified endpoint |
--user "test@liferay.com:learn" | Basic authentication credentials |
Basic authentication is used here for demonstration purposes. For production, you should authorize users via OAuth2. See Using OAuth2 to Authorize Users for a sample React application using OAuth2.
Examine the Java Class
The Groups_POST_ToInstance.java
class adds a SCIM group by calling the GroupResource
service.
This class invokes the REST service using only three lines of code:
Line (abbreviated) | Description |
---|---|
GroupResource.Builder builder = ... | Get a Builder for generating a GroupResource service instance. |
GroupResource groupResource = builder.authentication(...).build(); | Use basic authentication and generate a GroupResource service instance. |
groupResource.postV2Group(...); | Call the groupResource.postV2Group method. |
Note that the project includes the com.liferay.scim.rest.client.jar
file as a dependency. You can find client JAR dependency information for all REST applications in the API explorer in your installation at /o/api
(e.g., http://localhost:8080/o/api).
The main
method’s comment demonstrates running the class.
See GroupResource for service details.
Groups_GET_FromInstance.sh
Command:
Code:
Groups_GET_FromInstance.java
Command:
Code:
The Group
objects of your Liferay instance are listed in JSON.
Read API Query Parameters for more information.
Get a Group
Get a specific group with the following cURL or Java command. Replace 1234
with the group’s ID.
Use Groups_GET_FromInstance.[java|sh]
to get a list of all groups, and note the id
of the group you want specifically.
Groups_GET_ById.sh
Command:
Code:
Groups_GET_ById.java
Command:
Code:
The Group
fields appear in JSON.
Using Query Parameters
You can filter the data you get by using query parameters. The example below gets groups by display name.
Groups_GET_ByDisplayName.sh
Command:
Code:
Query parameters can also be used to refine the data returned. For example, when querying the Group
resource, you can prevent the list of members from being returned by modifying the query in the script above like this:
Put a Group
Update an existing group with the following cURL and Java commands. Replace 1234
with your group’s ID.
Groups_PUT_ById.sh
Command:
Code:
Groups_PUT_ById.java
Command:
Code:
Delete a Group
Delete an existing group with the following cURL and Java commands. Replace 1234
with your group’s ID.
Groups_DELETE_ById.sh
Command:
Code:
Groups_DELETE_ById.java
Command
Code:
Patch a Group
Liferay DXP 2025.Q2+
Patch an existing group with the following cURL command. Replace 1234
with your group’s ID.
Command:
Code:
The API Explorer lists all of the Group
services and schemas and has an interface to try out each service.