SCIM User API Basics
Liferay DXP 2024.Q1+
Liferay provides a headless API to perform CRUD operations on SCIM users to keep their identity information in sync with your company’s applications. Use the /scim
endpoint from the API Explorer to manage SCIM users.
Adding a User
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 User API Basics.
-
Use the cURL script to add a SCIM user in Liferay. On the command line, navigate to the
curl
folder. Execute theUser_POST_ToInstance.sh
script.The JSON response shows the addition of a new SCIM user:
-
Verify this by opening the Global Menu (
), and navigating to Control Panel → Users and Organizations. See that a new user has been added.
-
Alternatively, call the REST service using the Java client. Navigate into the
java
folder and compile the source files: -
Run the
User_POST_ToInstance
class.
Examine the cURL Command
The User_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/Users" | The REST service endpoint |
--data-raw "{ "active": "'true'", "emails": [ { "primary": "'true'", "type": "default", "value": "able@liferay.com" } ], "name": { "familyName": "Baker", "givenName": "Able" }, "userName": "able.baker" }" | 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 User_POST_ToInstance.java
class adds a SCIM user by calling the UserResource
service.
This class invokes the REST service using only three lines of code:
Line (abbreviated) | Description |
---|---|
UserResource.Builder builder = ... | Get a Builder for generating a UserResource service instance. |
UserResource userResource = builder.authentication(...).build(); | Use basic authentication and generate a UserResource service instance. |
userResource.postV2User(...); | Call the userResource.postV2User 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 UserResource for service details.
Users_GET_FromInstance.sh
Command:
Code:
Users_GET_FromInstance.java
Command:
Code:
The User
objects of your Liferay instance are listed in JSON.
Read API Query Parameters for more information.
Get a User
Get a specific user with the following cURL or Java command. Replace 1234
with the user’s ID.
Use Users_GET_FromInstance.[java|sh]
to get a list of all users, and note the id
of the user you want specifically.
User_GET_ById.sh
Command:
Code:
User_GET_ById.java
Command:
Code:
The User
fields are listed in JSON.
Put a User
Update an existing user with the following cURL and Java commands. Replace 1234
with your user’s ID.
User_PUT_ById.sh
Command:
Code:
User_PUT_ById.java
Command:
Code:
Deactivate a User
Deactivate an existing user with the following cURL and Java commands. Replace 1234
with your user’s ID.
User_DELETE_ById.sh
Command:
Code:
User_DELETE_ById.java
Command
Code:
The API Explorer lists all of the User
services and schemas and has an interface to try out each service.