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,
-
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
-
Use the cURL script to add a SCIM group in Liferay. On the command line, navigate to the
curl
folder. Execute theGroup_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" }
-
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:javac -classpath .:* *.java
-
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:
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 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).
The main
method’s comment demonstrates running the class.
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.
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.