SCIM Group API Basics

Liferay DXP 2024.Q1+ Beta Feature

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:2024.q2.11

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,

  1. Download and unzip SCIM Group API Basics.

    curl https://resources.learn.liferay.com/dxp/latest/en/installation-and-upgrades/securing-liferay/developer-guide/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 Group_POST_ToInstance.sh script.

    ./Group_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 (Applications Menu icon), and navigating to Control PanelUsers Groups. See that a new user group has been added.

    See that a new 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 Group_POST_ToInstance class.

    java -classpath .:* Group_POST_ToInstance
    

Examine the cURL Command

The Group_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 "test@liferay.com:learn"

Here are the command’s arguments:

ArgumentsDescription
"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
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 Group_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(
		"test@liferay.com", "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 "test@liferay.com: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(
		"test@liferay.com", "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.

Group_GET_ById.sh

Command:

./Group_GET_ById.sh 1234

Code:

curl \
   "http://localhost:8080/o/scim/v1.0/v2/Groups/${1}" \
   --user "test@liferay.com:learn"

Group_GET_ById.java

Command:

java -classpath .:* -DgroupId=1234 Group_GET_ById

Code:

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

	GroupResource groupResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

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

The Group fields are listed in JSON.

Put a Group

Update an existing group with the following cURL and Java commands. Replace 1234 with your group’s ID.

Group_PUT_ById.sh

Command:

./Group_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 "test@liferay.com:learn"

Group_PUT_ById.java

Command:

java -classpath .:* -DgroupId=1234 Group_PUT_ById

Code:

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

	GroupResource groupResource = builder.authentication(
		"test@liferay.com", "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.

Group_DELETE_ById.sh

Command:

./Group_DELETE_ById.sh 1234

Code:

curl \
   "http://localhost:8080/o/scim/v1.0/v2/Groups/${1}" \
   --request "DELETE" \
   --user "test@liferay.com:learn"

Group_DELETE_ById.java

Command

java -classpath .:* -DgroupId=1234 Group_DELETE_ById

Code:

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

	GroupResource groupResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

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

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

Capabilities

Product

Contact Us

Connect

Powered by Liferay
© 2024 Liferay Inc. All Rights Reserved • Privacy Policy