Creating an OAuth2 Application

When you have an application that can use OAuth 2.0 for authorization, you must register that application so Liferay can recognize it.

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

   Here, you can view a list of the existing OAuth 2 applications, if any.

2. Click New.

3. Fill out the form (description below).

4. Click Save to save the application.

   

This adds the application to the list of OAuth 2 apps and opens it in Edit mode. If you go back to the OAuth 2 Administration page, the saved app appears as a new entry. Click Actions () to view, edit, or delete the app.

Note

Once the app has authorizations, you can also revoke all of them at once by clicking Actions () and selecting Revoke Authorizations.

Next, you must enter necessary information and define scopes of data the application can access.

OAuth2 Administration Reference

Name: Give the application a recognizable title.

Website URL: Add a link to the application’s website.

Callback URIs: Enter at least one (line-separated) URI where users should be redirected after they authorize (or refuse to authorize) access to their accounts. This should link to a handler for whichever Allowed Authorization Types you support (see below).

Privacy Policy URL: Enter the link to your application’s privacy policy page.

Client Authentication Method: Choose from None, Client Secret Basic or Post, Client Secret JWT, and Private Key JWT.

JSON Web Key Set: When choosing Private Key JWT as the Client Authentication Method in the drop-down above, you must paste your application’s public JWKS. You can leave this blank when choosing other authentication methods.

Client Profile: Choose a template that filters the authorization types that are appropriate (secure) for that profile. For example, if your application is a web application, choose Web Application, and these authorization types are available and selected automatically: Authorization Code, Client Credentials, Refresh Token, and Resource Owner Password Credentials. These are OAuth 2 “flows” documented in the OAuth2 RFC 6749 Standards Document. If you want to select authorization types manually, select Other.

Allowed Authorization Types: Select the defined OAuth 2 protocol flows your application supports. Several common combinations are defined for you in the various Client Profiles above.

Client Credentials User: Select the user whose credentials should be used for the Client Credentials authorization type. This is only applicable for the Client Credentials authorization type.

Trusted Application: For Authorization Code and PKCE Extended Authorization Code flows, check this box to consent to the access token automatically, without requiring the user to allow it.

Remember Device: For Authorization Code and PKCE Extended Authorization Code flows, check this box to allow users to grant access automatically on their chosen devices when access tokens expire.

After you save the form, it reappears with additional fields:

Client ID: The system generates this for you; it’s an identifier for your application, so that DXP knows what application is being authorized to access user data.

Client Secret: Click Edit → Generate New Secret to generate a client secret. The secret identifies the client during the authorization process (see figure 1 above). Not all client profiles require a client secret, because some are incapable of keeping it secret! This is when the aforementioned PKCE code challenge and verifier is needed.

Icon: Upload an icon that your application’s users identify with your application. This is displayed on the authorization screen.

Privacy Policy URL: Add a link to your application’s privacy policy.

Token Introspection: Allow your application to retrieve metadata from the token by requesting it from DXP. This implements RFC 7662.

Configuring Scopes

After entering the necessary app information, you must define the scopes of data the app can access. Go to the Scopes tab to configure this.

The Scopes tab contains an extensive list of Liferay data represented using their fully qualified names. You can define three types of access:

• Read
• Write
• Everything

Select an entity, check the box to determine the scope, and click Save.

Authorizations

The Authorizations tab contains a list of authorizations approved by Liferay for the app. You can click Revoke to remove individual authorizations or go back to the OAuth 2 Administration page and use the app’s Revoke Authorizations option to remove all authorizations.

Retrieving Client ID Remotely

Liferay DXP 7.4 U55+/GA55+

Liferay provides an endpoint to retrieve an OAuth 2 application’s client ID using its external reference code. While applications created from the UI don’t have their external reference code displayed, you can use the following SQL command to retrieve it from the database. Replace <YOUR_APP_NAME> with the name of your OAuth 2 application.

SELECT EXTERNALREFERENCECODE FROM OAUTH2APPLICATION WHERE NAME LIKE '[YOUR_APP_NAME]';

Then, use the external reference code in the following cURL command to retrieve the app’s client ID:

curl \
   -G \
   --data-raw 'externalReferenceCode=[OAUTH_APP_ERC]' \
   http://{hostname}/o/oauth2/application

Replace [OAUTH_APP_ERC] with the external reference code of your OAuth 2 application.

Note

If you’re creating an OAuth 2 application via API, you can specify the external reference code to use.