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.

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
Release 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
Release Feature LPD-63415 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
Release Feature LPD-63415 OAuth 2.0 Protected Resource Metadata (RFC 9728)	Defines a standardized metadata document a resource server uses to advertise the authorization servers it trusts at a /.well-known endpoint.	Supported where applicable.	RFC 9728
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
Liferay DXP 2026.Q3+<br/> Resource Indicators for OAuth 2.0 (RFC 8707) | Defines theresource parameter clients send to name the protected resources an access token is meant for.	Supported on the Authorization Code and Client Credentials grants.	RFC 8707

Authorization Server Metadata (RFC 8414)

Release Feature

Liferay DXP 2026.Q1+

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 OpenId Configuration tab adds the OpenID Connect-specific fields.

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 endpoint. 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

Discovery Endpoint

When at least one metadata entry is enabled, Liferay exposes this well-known endpoint:

• /.well-known/oauth-authorization-server (RFC 8414)

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

OAuth Authorization Server Discovery

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

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

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.

Requesting a Specific Issuer

To reach one entry’s metadata directly, append the issuer’s own path to the well-known path, as RFC 8414 prescribes. An entry whose Issuer is https://example.com/o/oauth2 publishes its metadata at

https://example.com/.well-known/oauth-authorization-server/o/oauth2

Liferay rebuilds the issuer from the requested host and path suffix, then looks for an enabled entry with that issuer. If no entry matches, or the matching entry is disabled, the endpoint returns 404.

Because Liferay rebuilds the issuer from the request, this form reaches only an entry whose Issuer names the Liferay instance serving the request, such as the instance’s own OAuth 2.0 authorization server. An entry describing an external authorization server is served only at the bare host-root endpoint above, and only when it’s the enabled entry created first.

Protected Resource Metadata (RFC 9728)

Release Feature

Liferay DXP 2026.Q3+

Liferay DXP supports OAuth 2.0 Protected Resource Metadata as defined in RFC 9728. A protected resource is any server whose data an OAuth access token guards, such as a headless API. When you publish this metadata, OAuth clients discover which authorization servers issue tokens for the resource without any per-client configuration.

To configure an entry,

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

2. Open the Protected Resource Local Metadata tab.

   

3. Click New.

4. Fill out the form:

   Field	Description
   Resource (required)	The HTTPS URL identifying the protected resource. Liferay validates that it’s a well-formed HTTPS URL and rejects duplicate resources before saving. Example: https://example.com/o/headless-delivery
   Resource Name	A human-readable name for the resource.
   Authorization Servers (required)	A comma-delimited list of authorization server issuer URLs that may issue tokens for this resource. Use the same value as the Issuer field of each authorization server’s own Authorization Server Metadata entry. Example: https://auth.mycompany.com/o/oauth2
   Supported Bearer Methods	A comma-delimited list of methods clients use to present a bearer token to this resource, such as header, body, or query (see RFC 6750). The default is header.
   Supported Scopes	A comma-delimited list of scopes the resource server supports.
   Enable	Activates the metadata entry. Only enabled entries are published at the well-known URI.

   Liferay also displays two read-only fields it generates from your input: Protected Resource Local Well-Known URI (the well-known URI where this entry’s metadata is published, derived from the Resource URL) and Protected Resource Metadata JSON (the metadata document published at that URI).

5. Click Save.

After you save an entry, it appears in the Protected Resource Local Metadata list with its resource and well-known URI. Visit the well-known URI to confirm Liferay returns the metadata JSON document.

Open a row’s Actions menu () to Edit or Delete that entry. You can also open an entry by clicking it in the list, or delete several entries at once by selecting their rows and clicking Delete in the management toolbar. A confirmation modal appears before Liferay deletes any entries.

Discovery Endpoint

Liferay generates each entry’s Protected Resource Local Well-Known URI by inserting /.well-known/oauth-protected-resource between the resource’s host and path. For example, a resource of https://example.com/o/headless-delivery publishes its metadata at https://example.com/.well-known/oauth-protected-resource/o/headless-delivery. Each resource on the same instance therefore publishes its metadata at a distinct well-known URI. Request an entry’s own well-known URI to reach its metadata directly.

The bare /.well-known/oauth-protected-resource at the host root also works, and covers a resource with no path (for example, https://example.com). If no metadata entry exists or none is enabled, any of these URIs returns 404.

The endpoint returns a JSON document generated from the enabled metadata entry and the fields configured in the UI, including resource, authorization_servers, bearer_methods_supported, and resource_name. It includes scopes_supported only when you set Supported Scopes.

Resource Indicators (RFC 8707)

Liferay DXP 2026.Q3+

Liferay DXP supports Resource Indicators for OAuth 2.0 as defined in RFC 8707. A client requests a token for one or more protected resources by sending one or more resource parameters to the token endpoint. Liferay records those values as the token’s audiences, and a resource server reads them to refuse a token that wasn’t issued for it.

Resource indicators work out-of-the-box. Support depends on the grant:

Grant Type	Honors resource
Authorization Code	Yes
Client Credentials	Yes
JWT Bearer	No
Refresh Token	No
Resource Owner Password	No

A grant that doesn’t honor resource ignores the parameter rather than rejecting the request.

Each resource value must be an absolute URI without a fragment. Repeat the parameter to request more than one audience. If any value is blank, relative, or carries a fragment, the token endpoint responds 400 with the error code invalid_target and issues no token.

Liferay stores the validated values with the authorization record.

The token introspection endpoint reports a token’s audiences in its aud member. When a token has one or more audiences, aud is always a JSON array of strings, regardless of the number of audiences. When a token has none, the response omits aud.

Liferay’s MCP server is the clearest consumer of this behavior: it accepts only tokens whose audiences include its resource URI. To obtain a valid token, send that URI as the resource parameter when requesting the token.

Feature Availability

Feature	Available as Beta	Available as Release	Generally Available
OAuth 2.0 Dynamic Client Registration (RFC 7591)	Liferay DXP 2026.Q1 LTS (LPD-63416)	Liferay DXP 2026.Q3 (LPD-63416)	-
OAuth 2.0 Authorization Server Metadata (RFC 8414)	Liferay DXP 2026.Q1 LTS (LPD-63415)	Liferay DXP 2026.Q3 (LPD-63415)	-
OAuth 2.0 Protected Resource Metadata (RFC 9728)	-	Liferay DXP 2026.Q3 (LPD-63415)	-

Next Steps

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