OpenID Connect in Liferay DXP

Introduction

OpenID Connect (OIDC) is an identity and authentication protocol built on top of OAuth 2.0.

OAuth 2.0 primarily addresses authorization, while OpenID Connect adds an authenti-

cation and identity layer. In a typical Liferay deployment:

User → Liferay → Identity Provider

Examples of identity providers include:

Keycloak
Okta
Microsoft Entra ID
Google Identity
Auth0
Other standards-compliant OpenID Connect providers

Liferay acts as an OpenID Connect Relying Party (RP), while the external authentication system acts as the OpenID Connect Provider (OP).

OAuth 2.0 vs OpenID Connect

A common source of confusion is the difference between OAuth 2.0 and OpenID Connect.

Feature	OAuth 2.0	OpenID Connect
Primary purpose	Authorization	Authentication and identity
Main question	What can the application access?	Who is the user?
Access Token	Yes	Yes
ID Token	No	Yes
User identity	Not its primary purpose	Core functionality
Built on	OAuth framework	OAuth 2.0

The important relationship is:

OpenID Connect = OAuth 2.0 + Identity Layer

Important Components

The major participants in an OpenID Connect authentication flow are:

End User

The person attempting to authenticate to the Liferay portal.

Liferay DXP

Liferay acts as the Relying Party (RP).

It trusts identity information provided by a configured OpenID Connect provider.

OpenID Provider

The OpenID Provider performs authentication. Examples include Keycloak, Okta, Auth0, Microsoft Entra ID, and other compatible providers.

Authorization Endpoint

The user’s browser is redirected to this endpoint so that the provider can authenticate the user.

Token Endpoint

After authorization, the client communicates with the token endpoint to obtain the appropriate tokens.

User Information Endpoint

This endpoint can provide additional information about the authenticated user.

JWKS URI

The JSON Web Key Set (JWKS) endpoint publishes public cryptographic keys that can be used to verify signed tokens.

High-Level Authentication Architecture

A simplified architecture is:

Diagram

+----------------+
|      User      |
+-------+--------+
       |
       | Access Liferay
       v
+----------------+
|  Liferay DXP   |
| Relying Party  |
+-------+--------+
       |
       | Redirect for authentication
       v
+----------------------+
| OpenID Provider      |
| Keycloak / Okta /    |
| Entra ID / Auth0     |
+----------+-----------+

Diagram

          |
          | Authenticate User
          v
+----------------------+
| Authorization Result |
+----------+-----------+
          |
          v
+----------------+
|  Liferay DXP   |
+-------+--------+
       |
       | Establish session
       v
+----------------+
| Authenticated  |
|     User       |
+----------------+

Typical Authentication Flow

The authentication sequence can be understood step-by-step.

Step 1: User Accesses Liferay

The user opens the Liferay portal.

Step 2: User Selects OpenID Connect

The user chooses OpenID Connect authentication from the Liferay sign-in interface.

Step 3: Redirect to Identity Provider

Liferay redirects the browser to the configured provider’s authorization endpoint. Conceptually:

Diagram

Browser
   |
   +----> Liferay
            |
            +----> OpenID Provider

Step 4: Provider Authenticates the User

The provider may authenticate the user using mechanisms such as:

username and password,
multi-factor authentication,
passwordless authentication,
smart cards,
enterprise directory credentials,
biometric-backed authentication.

The authentication mechanism is primarily controlled by the identity provider.

Step 5: Authorization Response

After successful authentication, the provider redirects the user back to Liferay.

Step 6: Token Processing

Liferay processes the authorization result and obtains the necessary tokens from the provider.

Step 7: Identity Verification

The ID Token contains identity-related claims. Typical claims can include:

Code

sub
name
given_name
family_name
email
preferred_username

Step 8: Liferay Session

After successful validation and user mapping, Liferay establishes an authenticated portal session.

ID Token

One of the most important additions provided by OpenID Connect is the ID Token. An ID Token is typically represented as a JSON Web Token (JWT):

JWT = Header.Payload.Signature

A conceptual payload could look like:

Code

{
  "iss": "https://identity.example.com",
  "sub": "248289761001",
  "aud": "liferay-client",
  "email": "user@example.com",
  "given_name": "Rajesh",
  "family_name": "Chaurasia"
}

Important claims include:

iss Issuer that created the token.

sub Subject identifier representing the user.

aud Audience for which the token was issued.

exp Expiration time.

iat Time at which the token was issued.

Registering Liferay with the Provider

Before Liferay can authenticate users through an external provider, Liferay must normally be registered as a client. The provider typically supplies:

Client ID
Client Secret
Issuer URL
Discovery Endpoint
Authorization Endpoint
Token Endpoint
User Information Endpoint
JWKS URI

The standard Liferay redirect URL is generally:

Code

https://[server.domain]/c/portal/login/openidconnect

For local development it could conceptually be:

Code

http://localhost:8080/c/portal/login/openidconnect

The redirect URI registered with the identity provider must match the Liferay configuration expected by the provider.

Discovery Endpoint

Modern OpenID Connect providers usually expose a discovery document. A common pattern is:

Code

https://provider.example.com/.well-known/openid-configuration

The discovery document can provide metadata such as:

issuer,
authorization endpoint,
token endpoint,
user information endpoint,
JWKS URI,
supported scopes,
supported signing algorithms.

This greatly simplifies configuration because the client does not need every endpoint to be manually entered.

Configuring OpenID Connect in Liferay

For the standard provider configuration, navigate approximately to:

Global Menu → Control Panel → Instance Settings → Security → SSO

Then select:

OpenID Connect Provider

and add the provider connection. Typical configuration properties include:

Property	Purpose
Provider Name	Human-readable identity provider name.
Scopes	Defines the identity information requested from the provider.
Discovery Endpoint	Provides OpenID Connect metadata and endpoint discovery.
Authorization Endpoint	Used to redirect users for authentication.
Issuer URL	Identifies the token issuer.
JWKS URI	Provides public keys for signature verification.
Token Endpoint	Used for requesting tokens.
User Information Endpoint	Provides additional authenticated user information.
Client ID	Identifies the Liferay client application.
Client Secret	Authenticates the client to the provider where required.
Custom Claims	Allows additional provider claims to be mapped into Liferay.

Enabling OpenID Connect

Creating a provider configuration alone does not necessarily enable OpenID Connect authentication. Navigate to:

Control Panel → Instance Settings → Security → SSO → OpenID Connect

Enable OpenID Connect authentication and save the configuration.

Users can then use the configured provider through the Liferay sign-in experience.

User Information Mapping

Identity providers and Liferay may use different names for the same user attributes. For example:

Liferay Attribute	OIDC Claim
firstName	given_name
lastName	family_name
emailAddress	email
screenName	preferred_username

Conceptually:

OIDC Claim −→ Liferay User Attribute

For example:

Code

given_name −→  firstName

Liferay also supports mapping appropriate OpenID Connect claims to Liferay custom user

fields.

Role Mapping

OpenID Connect identity information may also be used for role-related mapping. Conceptually:

Diagram

OIDC Provider
    |
    | roles / claims
    v
Liferay User
    |
    v
Liferay Roles

For automatic role assignment, the corresponding role must exist in Liferay and satisfy the requirements expected by Liferay’s mapping mechanism. This enables centralized identity systems to participate in application-level authorization.

Authentication vs Authorization

It is important to distinguish these concepts.

Authentication

Authentication answers:

Who are you?

OpenID Connect primarily addresses authentication and identity.

Authorization

Authorization answers:

What are you allowed to do?

In Liferay, authorization is typically governed using:

roles,
permissions,
organizations,
sites,
user groups,
resource permissions.

Therefore:

OIDC Authentication̸ = Liferay Authorization

They work together, but solve different problems.

Security Considerations

Use HTTPS

Production systems should use HTTPS. Without TLS, authentication traffic can become vulnerable to interception or manipulation.

Protect the Client Secret

Never expose a client secret in:

JavaScript,
public repositories,
JSP pages,
browser-visible configuration,
log files.

Validate Token Signatures

Tokens must be cryptographically verified.

The provider’s JWKS endpoint supplies the public keys needed for signature verification.

Validate Issuer

The token issuer should match the configured trusted provider.

Properties

token.iss = configured issuer

Validate Audience

The token should have been issued for the expected client.

Code

token.aud ⊇Liferay Client ID

Validate Expiration

Expired identity tokens must not be accepted.

tcurrent < texpiration

Use Appropriate Scopes

Applications should request only the identity information they actually require. Typical OIDC scopes include:

Code

openid
profile
email

PKCE

Liferay supports Proof Key for Code Exchange (PKCE) as an OpenID Connect client. PKCE introduces a dynamically generated verifier and challenge into the authorization flow. Conceptually:

code_verifier −→ H(code_verifier) −→ code_challenge

The authorization request sends the challenge. Later, the token request supplies the verifier. The authorization server verifies:

H(received verifier) = original challenge

This strengthens authorization-code flows against certain forms of authorization-code interception.

Single Sign-On

OpenID Connect is useful for Single Sign-On (SSO). Suppose an organization has:

Employee Portal
Liferay DXP
Learning Platform
Support Portal
Internal Applications

All applications can delegate authentication to the same identity provider. Conceptually:

Diagram

       +-------------------+
       | Identity Provider |
       +---------+---------+
                |
    +-------------+-------------+
    |           |           |
    v           v           v
Liferay       Application A  Application B

The identity provider becomes the centralized authentication authority.

OpenID Connect vs SAML

Both technologies are commonly used for enterprise SSO.

Feature	OpenID Connect	SAML
Foundation	OAuth 2.0	XML-based SAML standard
Typical token format	JWT / JSON	XML assertion
Common usage	Modern web/mobile/API ecosystems	Enterprise SSO and legacy integrations
Developer experience	Often REST/JSON friendly	More XML-oriented
Identity federation	Yes	Yes

Neither protocol is universally “better.” The appropriate choice depends on the identity

infrastructure, application architecture, security requirements, and organizational standards.

Troubleshooting

Provider Does Not Appear

Check that:

OpenID Connect is enabled.
The provider configuration is saved.
The discovery endpoint is reachable from the Liferay server.

Redirect URI Error

A common identity-provider error is:

Code

redirect_uri_mismatch

Verify that the redirect URI configured at the provider matches the URI used by Liferay.

Invalid Client

An error such as:

Code

invalid_client

usually indicates a problem with:

Client ID
Client Secret
provider configuration

User Attributes Missing

Check:

requested scopes,
provider claims,
UserInfo response,
Liferay user mapping configuration.

Discovery Endpoint Failure

From the Liferay server, test whether the provider metadata can actually be reached:

Shell

curl https://provider.example.com/.well-known/openid-configuration

Firewall rules, proxies, DNS problems, or TLS issues may prevent Liferay from reaching the provider.

Example Enterprise Architecture

Consider the following architecture:

Diagram

+----------------------+
| Employee Browser     |
+----------+-----------+
          |
          v
+----------------------+
|      Liferay DXP     |
| Portal / Applications|
+----------+-----------+
          |
          | OIDC
          v
+----------------------+
| Identity Provider    |
| Keycloak / Entra ID  |
+----------+-----------+
          |
          v
+----------------------+
| Enterprise Directory |
| LDAP / AD / Users    |
+----------------------+

The responsibilities can be separated as follows:

Identity Provider: Authentication and identity federation.

Liferay: Portal session, roles, permissions, sites, applications, and business functionality.

Enterprise Directory: Authoritative organizational identity information where applicable.

Single Logout

Modern Liferay DXP releases also support OpenID Connect Back-Channel Logout.

The provider can notify Liferay through a server-to-server request that an OpenID Connect

session has ended. The Liferay back-channel endpoint follows the pattern:

Code

https://your-liferay-domain/o/open_id_connect/backchannel_logout

The important architectural difference is:

Diagram

Normal Login:

Browser -> Liferay -> OIDC Provider

Diagram

Back-Channel Logout:

OIDC Provider ---------> Liferay
            server-to-server

This mechanism does not depend on the user’s browser delivering the logout notification.

Feature availability depends on the specific Liferay DXP release.

Interview and Revision Notes

Multiple Choice Questions

Question 1

OpenID Connect is primarily used for:

A. Database replication

B. Authentication and identity

C. Java dependency management

D. Liferay indexing

Answer: B

Question 2

OpenID Connect is built on top of:

A. LDAP

B. Kerberos

C. OAuth 2.0

D. JDBC

Answer: C

Question 3

In a standard external OIDC integration, Liferay primarily acts as:

A. OpenID Provider

B. Relying Party

C. Certificate Authority

D. LDAP server

Answer: B

Question 4

Which token is specifically introduced by OpenID Connect for identity information?

A. Refresh Token

B. Access Token

C. ID Token

D. CSRF Token

Answer: C

Question 5

Which endpoint normally publishes the provider’s public signing keys?

A. Token Endpoint

B. JWKS URI

C. Redirect URI

D. Logout Page

Answer: B

Question 6

What is the purpose of the sub claim?

A. Store the user’s password

B. Identify the token encryption algorithm

C. Uniquely identify the subject

D. Specify the HTTP method

Answer: C

Question 7

Which claim identifies the intended recipient of a token?

A. aud

B. exp

C. iss

D. iat

Answer: A

Question 8

What does PKCE primarily strengthen?

A. Database encryption

B. Authorization-code exchange

C. Liferay indexing

D. LDAP replication

Answer: B

Quick Reference

Concept	Meaning
OIDC	Authentication and identity protocol
OAuth 2.0	Authorization framework
RP	Relying Party, such as Liferay
OP	OpenID Provider
ID Token	Identity claims about authenticated user
Access Token	Authorization for protected resources
JWKS	Public keys for token verification
Discovery	Provider metadata discovery
PKCE	Protection for authorization-code exchange
SSO	Single Sign-On

Key Takeaway

The central idea behind OpenID Connect integration in Liferay is:

External Identity Provider → Authenticate User → OIDC Identity → Liferay Session

OpenID Connect allows Liferay to delegate authentication to a central identity platform

while Liferay continues to control portal-level roles, permissions, sites, applications, and other authorization concerns.

Official Reference

For current configuration details and version-specific behavior, refer to the official Liferay documentation:

Code

https://learn.liferay.com/w/dxp/security-and-administration/security/
               configuring-sso/using-openid-connect