Liferay DXP includes a script console which administrators can use to invoke Liferay DXP’s API. See the Using Liferay DXP’s Script Console article for more information. Liferay DXP’s API can also be invoked remotely. How is this possible? Liferay DXP includes a utility called the Service Builder which is used to generate all of the low level code for performing CRUD operations for entities that are saved to Liferay DXP’s database. This utility is further explained in the tutorial Service Builder. Service Builder generates web service interfaces that can be invoked remotely. Since Liferay DXP’s APIs are generated by Service Builder, the method signatures and behavior for storing and retrieving Liferay DXP objects are consistent.
Because the actual method calls for retrieving data are the same regardless of how one gets access to those methods (i.e., locally or through web services), Liferay DXP provides a consistent interface for accessing portal data that few other products can match. The actual interfaces for the various services can be found by navigating to Liferay DXP’s JSON web services page: http://localhost:8080/api/jsonws. Before these services can be invoked, administrators need to enable users to access these services remotely.
Liferay DXP includes four layers of web service security:
- IP permission layer
- Service access policy layer
- Authentication/verification layer (browser-only):
- User permission layer
Please see the Service Access Policies documentation for a description of these security layers.
In the default portal.properties file, there is a section called Main
Servlet. This section defines the security settings for all of the remote
services provided by Liferay DXP. Copy this section and paste it into your custom
portal-ext.properties file. Then you can edit the default values to configure
the security settings for the Axis Servlet, the Liferay Tunnel Servlet, the
Spring Remoting Servlet, the JSON Tunnel Servlet, and the WebDAV servlet.
By default, a user connecting from the same machine Liferay DXP is running on can access remote services so long as that user has the permission to use those services in Liferay DXP’s permissions system. Of course, you are not really “remote” unless you are accessing services from a different machine. Liferay DXP has multiple layers of security when it comes to accessing its services remotely. Without explicit rights granted for each layer, attempting to invoke a Liferay DXP API function remotely fails and a remote exception is thrown.
The first layer of web service security that a user needs to get through in
order to call a method from the service layer is servlet security. This is the
IP permission layer listed above. The Main Servlet section of the
portal-ext.properties file is used to enable or disable access to Liferay DXP’s
remote services. In this section of the properties file, there are properties
for each of Liferay DXP’s remote services.
You can set each service individually with the security settings that you
require. For example, you may have a batch job which runs on another machine in
your network. This job looks in a particular shared folder on your network and
uploads documents to your site’s Documents and Media portlet on a regular basis,
using Liferay DXP’s web services. To enable this batch job to get through the first
layer of security, you would modify the portal-ext.properties file and put the
IP address of the machine on which the batch job is running in the list for that
particular service. For example, if the batch job uses the Axis web services to
upload the documents, you would enter the IP address of the machine on which the
batch job is running to the axis.servlet.hosts.allowed property. A typical
entry might look like this:
axis.servlet.hosts.allowed=192.168.100.100, 127.0.0.1, SERVER_IP
If the machine on which the batch job is running has the IP address
192.168.100.100, this configuration will allow that machine to connect to
Liferay DXP’s web services and pass in user credentials to be used to upload the
documents.
The second layer of web service security is the service access policy layer. When attempting to invoke a Liferay DXP API function remotely, the function must be whitelisted by one of the service access policies that apply to the request.
The third layer of security is the authentication/verification layer. This layer is only applied to a Liferay DXP API function invocation request if the request is coming from a browser. In this case, the request must include a valid authentication token.
The fourth and final layer of security is Liferay DXP’s permissions system that protects every Liferay DXP entity. The user account that accesses the services remotely must have the proper permissions to operate on the objects it attempts to access. Otherwise, a remote exception is thrown. Portal administrators need to use Liferay DXP’s permissions system to grant access to these resources to the administrative user account that attempts to operate on them remotely. For example, suppose that a Documents and Media folder called Documents has been set up in a site. A role has been created called Document Uploaders which has the rights to add documents to this folder. Your batch job will be accessing Liferay DXP’s web services in order to upload documents into this folder. In order for this to work, you have to call the web service using a user account to which the Document Uploaders role has been assigned (or that has individual rights to add documents to the folder). Otherwise, you will be prevented from using the web service.
You can invoke a Liferay DXP web service in a variety of ways. For example, you can invoke a web service by navigating to a specific URL in your browser, by using the cURL tool, or via JavaScript. Here’s an example URL for a Liferay DXP web service invocation using a browser:
http://localhost:8080/api/jsonws/user/get-user-by-email-address/company-id/20154/email-address/test%40liferay.com?p_auth=[value]
This Liferay DXP web service invocation returns the user with the email address
test@example.com in the company (portal instance) with the ID 20154. Note
that for the web service invocation to succeed, you must supply a correct value
for the p_auth URL parameter. You can find such a value by signing in to
Liferay DXP, navigating to
http://localhost:8080/api/jsonws and
clicking on any function that appears in the list. Use the value for the
p_auth token that appears under the Execute heading. For more examples of
Liferay DXP web service invocations, please see the JSON Web
Services Invocation Examples documentation.
Some methods of invoking Liferay DXP web services (e.g., using cURL) allow you to supply a username and password. Note that Password Policies (covered in the User Management documentation) can be used in combination with this feature. If you are enforcing password policies on your users (requiring passwords to take a certain form, requiring users to change their passwords on a periodic basis, etc.), any administrative user account which accesses Liferay DXP’s web services in a batch job can have its password expire too.
To prevent this from happening, you can add a new password policy which does not enforce the password expiration and add your administrative user ID to it. Then your batch job can run as many times as you need it to and the administrative user account’s password will never expire.
In summary, accessing Liferay DXP remotely requires the successful passing of four security checks:
- The IP address must be pre-configured in the server’s
portal-ext.propertiesfile. - At least one service access policy which applies to the request must have the API function being invoked in a whitelist.
- If a browser is making the web service invocation request, a valid
authentication token (
p_authURL parameter) must be provided. - The user ID being used must have permission to access the resources it attempts to access.
Accessing Liferay DXP’s JSON Web Services
To see which Liferay DXP service methods are registered and available for use via JSON web services, open your browser to the following address:
http://localhost:8080/api/jsonws
The page lists the portal’s registered and exposed service methods. Get each method’s details by clicking the method name. You can view the full signature of each method, all its arguments, the exceptions that can be thrown, and its Javadoc! Using a simple form from within your browser, you can even invoke the service method for testing purposes.
To list registered services on a plugin (e.g. a custom portlet), don’t forget to use its context path in your URL:
http://localhost:8080/[plugin-context]/api/jsonws
This lists the JSON Web Service API for the plugin.
Accessing Liferay DXP’s WSDL
After configuring the security settings properly, your first step in obtaining access to Liferay DXP’s remote SOAP web services is to access the WSDL. If you are on a browser on the same machine Liferay DXP is running on, you can do this by accessing the following URL:
http://localhost:[port number]/tunnel-web/axis
If, for example, you are running on Tomcat on port 8080, you would specify this URL:
http://localhost:8080/tunnel-web/axis
If you are accessing a web service that was created as part of a portlet plugin, the URL is similar, but uses the context of your application rather than the tunnel-web servlet. You can get a list of your Service Builder-generated WSDL documents by using the URL pattern below:
http://localhost:8080/your-portlet/axis
If you are on a different machine from the Liferay DXP server, you will need to pass in your user credentials on the URL to access the WSDL:
http://[user ID]:[password]@[server name]:[port number]/tunnel-web/axis
In any case, once you successfully browse to this URL, you will see the list of web services. You can access the WSDL for each service by clicking on the WSDL link next to the name of the service. There are many services; one for each of the services available from the Liferay DXP API.
Once you click on one of the WSDL links, the Web Service Definition Language document will be displayed. This document can be used to generate client code in any language that supports it. You can either save the document to your local machine and then generate the client code that way, or use your tool to trigger Liferay DXP to generate the document dynamically by using one of the URLs above. For information about developing applications that leverage Liferay DXP’s remote services, please see the Invoking JSON Web Services documentation.