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

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

2. Click New.

3. Enter a name and relevant callback URIs.

4. In the Client Authentication Method drop-down, choose Private Key JWT.

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

6. Choose Client Credentials under Allowed Authorization Types.

   Note

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

7. 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):

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

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.