Client Secret JWT

Liferay supports client secret JWT as an authentication method for OAuth 2 clients. In this flow, the client itself creates the assertion and signs it using the client secret. Liferay authenticates the client by decoding the JWT assertion and verifying the signature using the client secret. Here, both the client and Liferay have possession of the client secret.

Important

All versions before Liferay DXP 2025.Q2 had a bug where the client secret in the OAuth 2 application was converted to its Base64 form resulting in an error when comparing the two. To overcome this on these versions of Liferay, you must replace the client secret of your OAuth 2 application in Liferay with its Base64 encoded version and use the unencoded client secret in your client to sign the JWT.

Advantages of Using Client Secret JWT

• It’s more secure than using basic client id + secret since you don’t send the client secret in the request.

• In addition to client authentication, it can also be used to verify additional claims present in the JWT.

• Since it uses standard JWTs, it improves interoperability between systems.

Creating an OAuth 2 Client

1. Open the Global Menu and navigate to Control Panel → OAuth 2 Administration.

2. Enter a name for the client and relevant callback URIs.

3. In the Client Authentication Method drop-down, choose Client Secret JWT.

4. Check the Client Credentials checkbox under Allowed Authorization Types.

Note

You can check the authorization code flow if your client requires authorization from a user. The client credentials flow doesn’t require user intervention.

5. Click Save.

Getting an Access Token from Liferay

Once you’ve configured your client to use client secret JWT, you can start getting access tokens from Liferay.

When using a confidential client, you must initiate a POST request to Liferay’s token URL https://[hostname]/o/oauth2/token with the following parameters in the body (encoded as application/x-www-form-urlencoded):

client_id=[YOUR_CLIENT_ID]

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer

client_assertion=JWT generated by the client

grant_type=client_credentials

Be sure to generate the JWT assertion with the required fields given below and sign it using a symmetric algorithm like (default is HS256).

Below is a sample token request made to Liferay using a JWT assertion from a client application.

Assertion Crafting

Your client assertion must meet the following conditions:

• The aud field in the JWT must match Liferay’s token URL (https://[hostname]/o/oauth2/token).

• The iss and sub fields of the JWT must match the client ID of the Liferay OAuth 2 client.

• The assertion must have an exp claim defining its expiry.