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

docker run -it -m 8g -p 8080:8080 liferay/dxp:2025.q1.6-lts

Sign in to Liferay at http://localhost:8080 using the email address [e-mail] and the password test. When prompted, change the password to learn.

Once Liferay is running,

1. Download and unzip SCIM Group API Basics.

   curl https://resources.learn.liferay.com/examples/liferay-p9z7.zip -O
   

   unzip liferay-p9z7.zip
   

2. Use the cURL script to add a SCIM group in Liferay. On the command line, navigate to the curl folder. Execute the Groups_POST_ToInstance.sh script.

   ./Groups_POST_ToInstance.sh
   

   The JSON response shows the addition of a new SCIM group:

   {
      "displayName": "Foo",
      "meta": {
         "created": "2024-03-13T11:51:35Z",
         "location": "http://localhost:8080/o/scim/v1.0/v2/Groups/36449",
         "lastModified": "2024-03-13T11:51:35Z",
         "resourceType": "Group"
      },
      "schemas": [
         "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "externalId": "eef7340d-3bc8-201b-76ae-411ec3a4ed1e",
      "id": "36449"
   }
   

3. Verify this by opening the Global Menu (), and navigating to Control Panel → Users Groups. See that a new user group has been added.

   

4. Alternatively, call the REST service using the Java client. Navigate into the java folder and compile the source files:

   javac -classpath .:* *.java
   

5. Run the Groups_POST_ToInstance class.

   java -classpath .:* Groups_POST_ToInstance
   

Examine the cURL Command

The Groups_POST_ToInstance.sh script calls the REST service with a cURL command.

curl \
"http://localhost:8080/o/scim/v1.0/v2/Groups" \
--data-raw '
	  {
		 "displayName": "Foo"
	  }' \
--header "Content-Type: application/scim+json" \
--request "POST" \
--user "[e-mail]:learn"

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 "[e-mail]:learn"	Basic authentication credentials

Note

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.

public static void main(String[] args) throws Exception {
	GroupResource.Builder builder = GroupResource.builder();

	GroupResource groupResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	groupResource.postV2Group(
		new Group() {
			{
				displayName = "Foo";
			}
		});
}

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).

Note

The main method’s comment demonstrates running the class.

Important

See GroupResource for service details.

Groups_GET_FromInstance.sh

Command:

./Groups_GET_FromInstance.sh

Code:

curl \
"http://localhost:8080/o/scim/v1.0/v2/Groups" \
--user "[e-mail]:learn"

Groups_GET_FromInstance.java

Command:

java -classpath .:* Groups_GET_FromInstance

Code:

public static void main(String[] args) throws Exception {
	GroupResource.Builder builder = GroupResource.builder();

	GroupResource groupResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(groupResource.getV2Groups(null, null));
}

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.

Tip

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:

./Groups_GET_ById.sh 1234

Code:

curl \
"http://localhost:8080/o/scim/v1.0/v2/Groups/${1}" \
--user "[e-mail]:learn"

Groups_GET_ById.java

Command:

java -classpath .:* -DgroupId=1234 Groups_GET_ById

Code:

public static void main(String[] args) throws Exception {
	GroupResource.Builder builder = GroupResource.builder();

	GroupResource groupResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		groupResource.getV2GroupById(
			String.valueOf(System.getProperty("groupId"))));
}

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:

./Groups_GET_ByDisplayName.sh 1234

Code:

curl \
	"http://localhost:8080/o/scim/v1.0/v2/Groups?filter=displayName%20eq%20%22${1}%22" \
	--user "[e-mail]:learn"

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:

http://localhost:8080/o/scim/v1.0/v2/Groups?excludedAttributes=members&filter=displayName%20eq%20%22${1}%22

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:

./Groups_PUT_ById.sh 1234

Code:

curl \
"http://localhost:8080/o/scim/v1.0/v2/Groups/${1}" \
--data-raw '
	  {
		 "displayName": "Bar"
	  }' \
--header "Content-Type: application/scim+json" \
--request "PUT" \
--user "[e-mail]:learn"

Groups_PUT_ById.java

Command:

java -classpath .:* -DgroupId=1234 Groups_PUT_ById

Code:

public static void main(String[] args) throws Exception {
	GroupResource.Builder builder = GroupResource.builder();

	GroupResource groupResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	groupResource.putV2Group(
		String.valueOf(System.getProperty("groupId")),
		new Group() {
			{
				displayName = "Bar";
			}
		});
}

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:

./Groups_DELETE_ById.sh 1234

Code:

curl \
"http://localhost:8080/o/scim/v1.0/v2/Groups/${1}" \
--request "DELETE" \
--user "[e-mail]:learn"

Groups_DELETE_ById.java

Command

java -classpath .:* -DgroupId=1234 Groups_DELETE_ById

Code:

public static void main(String[] args) throws Exception {
	GroupResource.Builder builder = GroupResource.builder();

	GroupResource groupResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	groupResource.deleteV2Group(
		String.valueOf(System.getProperty("groupId")));
}

Patch a Group

Liferay DXP 2025.Q2+

Patch an existing group with the following cURL command. Replace 1234 with your group’s ID.

Command:

./Groups_PATCH_ById.sh 1234

Code:

The API Explorer lists all of the Group services and schemas and has an interface to try out each service.

Related Topics

• Consuming REST Services