Introduction
In modern business systems, microservices are widely used to build apps that are easy to scale and maintain. Liferay allows integration of microservices by creating client extensions. Microservice client extensions are standalone applications that communicate with Liferay. They act as a proxy between Liferay and the microservice.
Liferay’s microservice client extensions communicate with Liferay using OAuth2 via headless APIs.Liferay provides a token to the microservice, using that token microservice can communicate with Liferay.
Prerequisites
Liferay DXP/Portal 7.4+
Basic knowledge of Liferay and Springboot
Experience in developing and deploying Liferay client extensions
Environment Requirements
Java
Liferay
What is a Microservice Client Extension?
A microservice client extension in Liferay is a modern way that allows developers to build and deploy independent Spring Boot microservices that connect with Liferay. Microservice runs as a standalone application and communicates with Liferay using headless APIs and OAuth2 authentication. Liferay allows the creation of several types of microservice client extensions, like Object Action, Workflow Action, Object Validation, and Notification Type. You can create these extensions by configuring the client-extension.yaml file.
//client-extension.yaml
assemble:
- fromTask: bootJar
ignek-sample-spring-boot:
.serviceAddress: localhost:58081
.serviceScheme: http
name: Ignek Sample Spring Boot OAuth Application User Agent
scopes:
- Liferay.Headless.Admin.User.everything
- Liferay.Headless.Admin.Workflow.everything
type: oAuthApplicationUserAgent
ignek-sample-spring-boot-notification:
name: Ignek Sample Spring Boot Notification
oAuth2ApplicationExternalReferenceCode: ignek-sample-spring-boot
resourcePath: /notification
type: notificationType
ignek-sample-spring-boot-object-action:
name: Ignek Sample Spring Boot Object Action
oAuth2ApplicationExternalReferenceCode: ignek-sample-spring-boot
resourcePath: /object/action/
type: objectAction
ignek-sample-spring-boot-object-entry-manager:
name: Ignek Sample Spring Boot Object Entry Manager
oAuth2ApplicationExternalReferenceCode: ignek-sample-spring-boot
resourcePath: /object/entry/manager
type: objectEntryManager
ignek-sample-spring-boot-object-validation-rule:
allowedObjectDefinitionNames:
- C_Employee
name: Ignek Sample Spring Boot Spring Boot Object Validation Rule
oAuth2ApplicationExternalReferenceCode: ignek-sample-spring-boot
resourcePath: /object/validation/rule
type: objectValidationRule
ignek-sample-spring-boot-workflow-action:
name: Ignek Sample Spring Boot Workflow Action
oAuth2ApplicationExternalReferenceCode: ignek-sample-spring-boot
resourcePath: /workflow/action
type: workflowAction
OAuth2 Administrator
The OAuth2 Administrator is the interface of Liferay that is integrated into the system and is used for administering OAuth2 applications and their settings. Once microservice client extensions are deployed on Liferay, the platform automatically generates OAuth2 applications for the microservice, which handle the authentication and authorization aspects between the Microservice and Liferay.
Liferay uses OAuth2 as the standard protocol to secure communication between microservices and the platform. Each microservice client extension requires an OAuth2 application to authenticate and access tokens. These tokens allow the microservice to make authorized API calls to Liferay’s headless REST APIs.
To access the OAuth2 Administrator in Liferay :
Log in to Liferay as an administrator
Navigate to Control Panel → Security → OAuth2 Administration
Auto-Generated OAuth2 Applications
When you deploy a microservice client extension with an OAuthApplicationUserAgent configuration (as shown in the client-extension.yaml example above), Liferay automatically creates an OAuth2 application with characteristics like clientId, Name, WebSiteURL, Scope, etc.
Scopes for Microservice
In Liferay, Scopes are permissions that define what resources and operations your microservice can access within Liferay. When Liferay provides an OAuth2 token to your microservice, the token has specific scopes that limit the API endpoints and actions. This follows the principle of least privilege, ensuring your microservice only has access to the resources it needs. It gives access with read, write, and everything options.
How to define scopes for a Microservice?
In Liferay, there are two ways to define the scope for a Microservice.
From OAuth2 Administration
From the client-extension.yaml file
- From OAuth2 Administration
Liferay automatically creates the OAuth2 application for the microservice after the deployment. You can define the scope for the microservice directly from the application, but when you define the scope from the application, it’s applied only until the microservice is not deployed again, because Liferay creates or updates the OAuth2 application based on the client-extension.yaml file. So you can define the scope of the application temporarily, not permanently.
You can define scopes for the Microservice from the OAuth2 Administration by following the steps :
Navigate to the control panel -> security -> OAuth2 Administration.
Click on your Microservice Application.
Navigate to the Scopes tab.
In this tab, you will see a list of all the scopes of the resources that you can define for the Microservice.
- Now, click on the scope that you want to define for the Microservice and give access with Read, Write, and Everything options based on your requirement.
Click on the save button.
- From the client-extension.yaml file
Liferay creates the OAuth2 Application for the microservice automatically based on its client-extension.yaml file. You can define the scopes that you need for your microservice in this file under the scopes: configuration. When you deploy the microservice on Liferay then it will automatically define scopes for it, and you don’t need to define it manually.
//client-extension.yaml
assemble:
- fromTask: bootJar
ignek-sample-spring-boot:
.serviceAddress: localhost:58081
.serviceScheme: http
name: Ignek Sample Spring Boot OAuth Application User Agent
scopes:
- Liferay.Headless.Admin.User.everything
- Liferay.Headless.Admin.Workflow.everything
type: oAuthApplicationUserAgent
Conclusion
Integrating microservices with Liferay through the client extensions is a smooth and efficient way to build applications. Using OAuth2 for secure communication between microservices or Liferay, developers can ensure that each service only has access to the necessary resources, all while maintaining flexibility in defining scopes and permissions. Defining scopes in the client-extension.yaml file is recommended for permanent configuration.
