Using Authentication Verifiers
Authentication Verifiers authenticate remote invocations of Liferay DXP’s API in a centralized and extensible way. They have two main responsibilities:
- Verify provided credentials using registered
AuthVerifierinstances - Create portal authorization contexts based on verification results
If no available AuthVerifier can determine that the provided credentials match a user account, an authorization context supporting non-authenticated access is created for a guest user. Therefore, each API exposes only a single API endpoint. In contrast, legacy (before 6.2) versions of Liferay Portal exposed two API endpoints for each API: the /api/endpoint URI was for non-authenticated access and the URI /api/secure/endpoint was for authenticated access.
There are built-in AuthVerifier implementations for the most common situations, such as when remote clients use HTTP Basic or HTTP Digest authentication, send credentials in request parameters, send authenticated JSESSIONIDs, or use shared secrets to establish trust. Other AuthVerifier implementations can be deployed as modules containing implementations of the AuthVerifier interface that are registered as services in the OSGi runtime.
The authentication verification layer’s focus is on verifying authentication, not on providing credentials. It does NOT issue tokens, credentials, or display Sign In portlets. Instead, the layer verifies existing credentials and authenticated sessions and is a complement to authentication endpoints. To ensure backwards compatibility the default implementations support requests providing user name and password credentials. Thus, the authentication verification layer stands on the border between authentication and authorization.
Authentication Verification Process
To configure Authentication Verifiers, go to Control Panel → System Settings → API Authentication.
Step 1: Verify Request Credentials
The layer uses the chain of responsibility design pattern to support both built-in and third party AuthVerifier implementations. Each AuthVerifier can provide configurations where it specifies mapped URLs and other properties.
Each incoming request is matched against all registered AuthVerifiers to select the final list of AuthVerifiers that is used to process the request. It’s the responsibility of each AuthVerifier to verify the incoming request credentials.
Step 2: Create an Authorization Context
When a request is processed by all matching AuthVerifiers, Liferay DXP creates an authorization context for the resolved user.
This encompasses setting the HttpServletRequest remoteUser to return the resolved user ID setting ThreadLocals to the resolved user.
The resolved user can be the user returned by one of the AuthVerifier instances or a guest user if no instance was able to verify the provided credentials.
Configuring Built-In Authentication Verifiers
Developers create AuthVerifiers, and Liferay processes them automatically once they’re registered in the OSGi runtime. The AuthVerifierFilter class, which implements the javax.servlet.Filter interface, provides this layer. Liferay DXP ships 13 configurations in the API Authentication category. Six of them configure an AuthVerifier: Basic Auth Header, Digest Authentication, Image Request, Portal Sessions, Request Parameter, and Tunnel Authentication. The other seven cover auto login, the HTTP tunnel extender, basic authentication protocol support, service access policies, and service access quotas.
- Auto Login Basic Authentication Header
- Auto Login Request Header
- Auto Login Request Parameter
- Basic Auth Header*
- Basic Authentication Protocol Support
- Digest Authentication (Deprecated)
- HTTP Tunnel Extender
- Image Request*
- Portal Sessions*
- Request Parameter
- Service Access Policies
- Service Access Quotas
- Tunnel Authentication*
Configurations marked with an asterisk ( * ) are enabled by default. Basic Auth Header and Portal Sessions work for remote API access as shipped. Image Request and Tunnel Authentication are limited to the Liferay DXP server, because their Hosts Allowed field defaults to 127.0.0.1,SERVER_IP.
The Liferay Commerce Connector to PunchOut2Go app adds one more configuration to this category, Auto Login Punch Out Access Token.
Basic Auth Header
With this Auth Verifier, a remote client can authenticate using HTTP Basic Authentication. Configure it by providing URL paths that should be authenticated this way. When the Force Basic Authentication field is checked, HTTP Basic Authentication is required.
The default URLs are /api/*,/xmlrpc* for web services. The mapping excludes /api/liferay* to prevent accessing TunnelServlet. See Tunnel Authentication Verifiers for the Auth Verifier that authenticates TunnelServlet requests.
Digest Authentication (Deprecated)
This Auth Verifier is deprecated as of Liferay DXP 7.4 and has no direct replacement.
With this Auth Verifier, a remote client can authenticate using HTTP Digest Authentication. Configure it by providing URL paths that should be authenticated this way. When the Force Digest Authentication field is checked, HTTP Digest Authentication is required.
This Auth Verifier is not enabled by default.
HTTP Tunnel Extender
As Liferay embraced modularity, this extender was written to enable modules to be part of TunnelServlet. It maps TunnelServlet and TunnelingServletAuthVerifier to the module servlet context. Modules with Http-Tunnel in the manifest can make use of the Tunnel Servlet, and can expose the API via /o/_module_/api/liferay/do.
In the Hosts Allowed field, enter the client IP addresses allowed to tunnel. The default, 255.255.255.255, matches no client, so no host can tunnel until you replace it. An empty field accepts any address. The tunnel.servlet.hosts.allowed portal property is a separate setting that restricts the tunnel servlet itself. See Tunnel Servlet for that property and Configuring Remote Live Staging for remote publishing.
Note that this is not a recommended way to export remote APIs; it’s far better to expose remote services using JAX-RS or Liferay JSON Web Service technologies.
Image Request Authentication Verifier
When connected to LibreOffice/OpenOffice, the Office process must download images from Liferay DXP to render docs with images. To do this, a JWT Token is created to access the images securely.
Configure this by setting the Hosts Allowed, URLs Includes, and URLs Excludes fields.
This Auth Verifier is enabled by default, but access is limited to the Liferay DXP server itself. Its Hosts Allowed field defaults to 127.0.0.1,SERVER_IP and its URLs Includes field to /documents/*,/image/*,/c/wiki/get_page_attachment.
Portal Sessions Auth Verifiers
Enables JavaScript in a browser to access Liferay JSON Web Services using an existing portal session.
In the default configuration, the URLs included field shields access to the legacy JSON remote services layer: /api/json*,/api/jsonws*,/c/portal/json_service*.
Request Parameter Auth Verifiers
For backwards compatibility with RequestParameterAutoLogin you can authenticate and access portal endpoints with credentials inside HTTP request parameters parameterAutoLoginLogin and parameterAutoLoginPassword.
This Auth Verifier is not enabled by default.
Tunnel Authentication Verifiers
TunnelServlet is a legacy remote API endpoint mapped at /api/liferay/do to provide access to the portal remote services. The Tunnel Auth Verifier grants trusted remote clients access on behalf of any user ID they send.
An example of a trusted remote client is the Staging remote publishing feature.
Trusted remote clients authenticate using a shared secret stored in the portal property tunneling.servlet.shared.secret, which is documented in HTTP Tunneling. The default value is empty and forbids all access.
This Auth Verifier is enabled by default, but its Hosts Allowed field defaults to 127.0.0.1,SERVER_IP, so only the Liferay DXP server can use it. To let other clients tunnel, add their IP addresses to that field. See Configuring Remote Live Staging for remote publishing.