Using OAuth 2.0

OAuth 2.0 is an industry-standard authorization protocol. Users with accounts on a Liferay-based website can share select credentials with various clients seamlessly. OAuth 2.0 works by authorizing password-less access to portions of user-owned resources (such as an email address, a user profile picture, or something else from your account) and other permissioned resources. OAuth 2.0’s design encrypts all authorization transport through HTTPS, which prevents data passed between the systems from being intercepted.

You can jump into creating OAuth 2.0 apps or continue reading to learn how it works.

1. Creating an OAuth 2.0 Application
2. Defining Scopes
3. Authorizing Account Access

Flow of OAuth 2.0

OAuth 2.0 takes advantage of web standards wherever possible: transport is encrypted with HTTPS; tokens are implemented as HTTP headers; data is passed via web services.

Here’s how OAuth 2.0 works:

1. A user accesses a third-party application that supports authorization via credentials from a Liferay-based website. In the application (web or mobile), the user requests authorization via OAuth, sending the browser or app to the Liferay-based website. When using the Proof Key for Code Exchange or PKCE flow (explained below), the application also generates a code verifier and sends a code challenge that is created by applying a transformation to it.

2. The user authenticates and is shown the resources the application wants permission to access. When the user gives permission by clicking Allow, Liferay generates an authorization code that’s sent to the application over HTTPS.

3. The application then requests a more permanent access token and sends the code with the request (along with the PKCE code verifier).

   Note

   If requesting a token on the same instance, Liferay produces no network traffic.

4. If the authorization code matches (and the transformed PKCE code verifier matches the previously sent code challenge), Liferay cryptographically generates an access token for this user and application combination. It sends the token to the application over HTTPS. Initial authorization is now complete!

5. When the application must retrieve data, it sends the token with the request to prove it’s authorized to have that data.

6. Provided the token matches what Liferay has for that user and application, access is granted to retrieve the data.

That description throws around a lot of terms. Definitions provided below.

Important

A user must have these two permissions to generate and view access tokens:

• Control Panel → Security → OAuth 2 Administration - OAuth 2 Application Entry → Create Token
• Control Panel → Security → OAuth 2 Administration - OAuth 2 Application Entry → View

OAuth 2.0 Terminology

Authentication: Providing credentials so a system can verify who you are by matching those credentials with what it has stored. OAuth is not an authentication protocol.

Authorization: Granting access to resources stored on another system. OAuth is an authorization protocol.

Application: Any client (web, mobile, etc.) that must be authorized to have access to resources. Applications must be registered by administrators before users can authorize access to their resources.

Client: Almost synonymous with application except that applications can have variants, such as web and mobile. These variants are clients.

Client ID: An identifier given to a client so it can be recognized.

Client Secret: A previously agreed-upon text string that identifies a client as a legitimate client.

Access Token: A cryptographically generated text string that identifies a user/client combination for access to that User’s resources.

Response Type: OAuth 2.0 supports several response types. Pictured and described above is the most common: the authorization code. Other response types are password (logging in with a user name and password), and client credentials (headless predefined application access).

Scope: A list of items that define what the application wants to access. This list is sent during the initial authorization request (or otherwise defaults to scopes selected in the application registration) so users can grant or deny access to their resources.

Callback URI: Also called a Redirection Endpoint URI. After authorization is complete, the authorization server (i.e., Liferay) sends the client to this location.

Technical Standards and Specifications

Liferay DXP implements OAuth 2.0 in the roles of Authorization Server and Resource Server, as defined by the OAuth 2.0 specifications. Compliance statements in this section apply only to these roles.

Liferay implements specifications published by the OAuth working group to promote interoperability and reduce vendor lock-in. While vendor-specific extensions may exist in certain DXP versions, Liferay addresses these requirements through external solutions rather than customizing Liferay DXP itself. Features that extend or adapt these specifications fall outside the scope of formal OAuth 2.0 compliance claims.

In the specifications listed below, the keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” are interpreted as described in RFC 2119.

For the OAuth 2.0 roles implemented by Liferay DXP, requirements marked as MUST (and equivalent terms) in the specifications are implemented and supported. Support for requirements marked as SHOULD or MAY varies by DXP version.

Specification	Description	Implemented in Liferay DXP	Link
OAuth 2.0 Authorization Framework (RFC 6749)	Defines OAuth roles, authorization flows, tokens, and scopes.	All MUST requirements for supported roles are implemented.	RFC 6749
Proof Key for Code Exchange (PKCE, RFC 7636)	Defines protections for the Authorization Code flow against interception attacks.	Supported for the Authorization Code flow.	RFC 7636
Bearer Token Usage (RFC 6750)	Specifies how bearer tokens are used to access protected resources.	All MUST requirements are implemented.	RFC 6750
OAuth 2.0 Token Introspection (RFC 7662)	Defines a mechanism for resource servers to query token state.	Supported where applicable.	RFC 7662
OAuth 2.0 Threat Model and Security Considerations (RFC 6819)	Specifies security threats and recommended mitigations.	Security recommendations are applied where relevant.	RFC 6819
Beta Feature LPD-63416 OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591)	Defines a standardized way for clients to register dynamically with an authorization server.	Supported where applicable.	RFC 7591
Beta Feature LPD-63415<br/> OAuth 2.0 Authorization Server Metadata (RFC 8414) | Defines a standardized metadata document that exposes authorization server capabilities at a/.well-known endpoint.	Supported where applicable.	RFC 8414
JWT Bearer Token Authorization Grant (RFC 7523)	Defines a JWT-based authorization grant for system integration.	Supported where applicable.	RFC 7523
JWT Profile for OAuth 2.0 Access Tokens (RFC 9068)	Defines a standard JWT-based access token format.	Supported where applicable.	RFC 9068

Authorization Server Metadata (RFC 8414)

Beta Feature

Liferay DXP 2026.Q1+

Important

Currently, this feature is behind a beta feature flag (LPD-63415). Read Beta Feature Flags for more information.

Liferay DXP supports OAuth 2.0 Authorization Server Metadata as defined in RFC 8414. To configure it,

1. Open the Global Menu (), go to the Control Panel, and click OAuth Client Administration under Security.

2. Open the Auth Server Local Metadata tab.

3. Select the OpenID Configuration or OAuth Authorization Server tab. Both tabs configure the same metadata entry. The difference is the well-known URI exposed and the OpenID Connect-specific fields available in the OpenID tab.

4. Click New.

5. Fill out the form (see below).

6. Toggle Enable to activate the metadata entry.

7. Click Save.

Issuer (required): The unique identifier of the Authorization Server. It identifies the authority that issues tokens. Example: https://auth.mycompany.com/o/oauth2

Supported Scopes: The scopes supported by the Authorization Server and published in the metadata document.

Supported Grant Types: The OAuth 2.0 grant types supported by the Authorization Server (for example, authorization_code, client_credentials).

Authorization Endpoint: The HTTPS URL where authorization requests are sent and users grant consent. Example: https://auth.mycompany.com/o/oauth2/authorize

JWKS URI: The HTTPS URL where the Authorization Server publishes its public signing keys. Example: https://auth.mycompany.com/o/oauth2/jwks

Token Endpoint: The HTTPS endpoint where clients exchange an authorization code or credentials for an access token. Example: https://auth.mycompany.com/o/oauth2/token

Enable (OAuth): Marks the metadata entry as active. Only enabled entries are returned by the discovery endpoints. Disabled entries are ignored, even if their issuer matches the request.

Registration Endpoint (OAuth): The HTTPS endpoint used for dynamic client registration when supported. Example: https://auth.mycompany.com/o/oauth2/registration

Supported Subject Types (OpenID): A JSON array describing how users are identified to clients. Must contain at least one value and include public. Example: ["public", "pairwise"]

UserInfo Endpoint (OpenID): The HTTPS endpoint where clients retrieve authenticated user claims when using OpenID Connect. Example: https://auth.mycompany.com/o/oauth2/userinfo

Note

The metadata JSON displayed in the UI is read-only and automatically generated based on the values entered in each field.

Discovery Endpoints

When at least one metadata entry is enabled, Liferay exposes the following well-known endpoints:

• /o/.well-known/oauth-authorization-server (RFC 8414)
• /o/.well-known/openid-configuration (OpenID Connect)

Each endpoint returns a JSON document generated from the enabled metadata entry and the fields configured in the UI.

OAuth Authorization Server Discovery

/o/.well-known/oauth-authorization-server returns OAuth 2.0 metadata, such as

• issuer
• authorization_endpoint
• token_endpoint
• jwks_uri
• supported grant types
• supported scopes

OpenID Connect-specific fields (for example, userinfo_endpoint and subject_types_supported) are only included in the OpenID Connect discovery endpoint.

In addition to the metadata returned, the endpoint follows this response behavior:

• If no metadata entry exists or none is enabled, the endpoint returns 404.

• If exactly one entry is enabled, that entry is returned.

• If multiple entries are enabled, Liferay returns the enabled entry created first.

If the request includes an issuer query parameter, Liferay attempts to match it to an enabled entry:

• If a matching entry is found and is enabled, it is returned.
• If a matching entry is found but is disabled, the endpoint returns 404.
• If no matching entry is found, the endpoint returns 404.

OpenID Connect Discovery

/o/.well-known/openid-configuration returns OpenID Connect metadata. In addition to the OAuth fields, it can include

• userinfo_endpoint
• subject_types_supported
• supported response types
• supported signing algorithms

Next Steps

• Creating an OAuth2 Application
• Authorizing Account Access with OAuth2
• OAuth 2.0 Scopes
• Using OAuth2 to Authorize Users