Using Private Key JWT (JSON Web Token)
Liferay supports private key JWT as an authentication method for OAuth 2 clients. In this flow, the client itself creates the assertion. Liferay authenticates the client by decoding the JWT assertion and verifying the signature using the client’s public key.
Advantages of Using Private Key JWT
- Since there’s no shared secret, it’s more secure than using basic client id + secret and client secret JWT authentication. The client generates a JWT assertion signed using its private key. The server verifies the signature using the client’s public key.
- It provides stronger repudiation due to the use of asymmetric key signing. The server can be sure of the client’s origin after verifying the signature.
- The server needn’t store client secrets.
- To change keys, the server must change its public key from the client.
Creating an OAuth 2 Client
-
Open the Global Menu (
) and navigate to Control Panel → OAuth 2 Administration.
-
Click New.
-
Enter a name and relevant callback URIs.
-
In the Client Authentication Method drop-down, choose Private Key JWT.
-
In the JSON Web Key Set input, paste your client’s JWKS. This is the client’s public key used to validate the JWT assertion signed using the client’s private key.
-
Choose Client Credentials under Allowed Authorization Types.
NoteYou can choose authorization code flow if your client requires authorization from a user. The client credentials flow doesn’t require user intervention.
-
Click Save.
Getting an Access Token from Liferay
Once you’ve configured your client to use Private Key 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
):
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 URLhttps://{hostname}/o/oauth2/token
. - The
iss
andsub
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.