liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/setup-oauth
setup-oauth
VerifiedCreate and configure the OAuth 2.0 application that a client extension needs to call Liferay Headless APIs, and the browser side client a fragment or widget needs to call a CET. Use when a CET of type objectAction, workflowAction, notificationType, siteInitializer, or any backend CET requires authenticated API access, or when browser code must call a client extension with a token. Called by scaffold-client-extension automatically when the CET type requires OAuth.
Setup OAuth
Generate the companion OAuth application entry inside client-extension.yaml and verify the deployed application is registered in Liferay.
When to Invoke
scaffold-client-extensionidentifies a CET type that requires OAuth (seerules/client-extension-types.md)- A CET is deployed but returns 401 or 403 on Liferay API calls
- The user says "set up OAuth", "configure OAuth for this extension"
Workflow
Identify the Required Scopes
Consult rules/oauth-scopes.md for the full scope table. Pick the minimum set that covers what the CET calls.
Examples:
- Object action that reads and writes entries:
c_<name>.everythingfor each object it calls - Site initializer:
Liferay.Headless.Site.everything - Batch data import only:
Liferay.Headless.Batch.Engine.everything
Add the OAuth Application Entry to client-extension.yaml
The OAuth companion type depends on the consuming CET — check rules/client-extension-types.md for the correct type and ERC field name for the CET you are wiring.
Microservice handler CETs (objectAction, workflowAction, notificationType, objectEntryManager, objectValidationRule) use oAuthApplicationUserAgent. The top level key of the OAuth entry — not its name field — is what goes in oAuth2ApplicationExternalReferenceCode on the CET.
Deploy time CETs (siteInitializer, batch) use oAuthApplicationHeadlessServer, referenced via the oAuthApplicationHeadlessServer field on the CET entry.
A Microservice With Its Own Identity
A microservice handler normally calls back into Liferay with the token Liferay sent it, which acts as whoever triggered the call. When that can be an anonymous visitor (an objectAction on an entry created by a public form), the token is Guest's and every callback returns 403 (manage-object-logic → "Calling Back Into Liferay From the CX"). Add an oAuthApplicationHeadlessServer entry to the same project and use it with grant_type=client_credentials for every callback. Keep the oAuthApplicationUserAgent entry: the handler CET still requires it as oAuth2ApplicationExternalReferenceCode.
<workspace-id>-action:
name: <WorkspaceId> Action
oAuth2ApplicationExternalReferenceCode: <workspace-id>-action-oauth-ua
resourcePath: /object/action/<name>
type: objectAction
<workspace-id>-action-oauth-hs:
.serviceAddress: localhost:3101
.serviceScheme: http
name: <WorkspaceId> Action OAuth (headless server)
scopes:
- Liferay.Headless.Admin.User.everything.read
- c_<objecta>.everything
- c_<objectb>.everything
type: oAuthApplicationHeadlessServer
<workspace-id>-action-oauth-ua:
.serviceAddress: localhost:3101
.serviceScheme: http
name: <WorkspaceId> Action OAuth (user agent)
scopes:
- Liferay.Headless.Object.everything
type: oAuthApplicationUserAgent
Verified on 2026.Q3.2, gradle-plugins-workspace 17.1.5:
- The token acts as
default-service-account, which has the Administrator role. Its scopes are the only thing that limits it, so list exactly what the microservice touches. Liferay.Headless.Object.everythingalone returns403on everything,/o/c/*included. Grantc_<objectname>.everythingfor each object the microservice reads or writes (<objectname>is the definition'sname, lowercased), plusLiferay.Headless.Admin.User.everything.readto read Accounts. With those, the generic object scope is not needed.- The token lasts 600 s and carries exactly the YAML scopes.
- The microservice reads its client ID and secret from files DXP writes on deploy, and both change on every redeploy: see "Token Acquisition" below.
- Verifying the inbound token: its JWT header has no
kid({"typ": "at+jwt", "alg": "RS256"}), while/o/oauth2/jwkspublishes one key withkid: "authServer". A verifier that looks the key up bykidfinds nothing and rejects every call. With nokid, try each published key, then checkclient_idagainst<ua-erc>.oauth2.user.agent.client.idin the routes, read again on each request because it rotates too. The object action payload'sobjectDefinitionIdis a string ("38575"). Verified on 2026.Q3.2.
Replace <workspace-id> with the value of id in client-extension.yaml.
Deploy
Run deploy-and-verify from the client extension root. Blade copies both entries to Liferay on deploy.
Token Acquisition (for Manual Testing)
Verified on 2026.Q3.2 for an oAuthApplicationHeadlessServer entry, whether it serves a siteInitializer/batch or a microservice that needs its own client_credentials identity:
- Every deploy rotates both the client ID and the secret, even one that changes nothing, and a token issued before it then gets
401. Never copy them into source control, a committed.env, or a log line. - On a server hosted locally, they are files under
${liferay.home}/routes/default/<project-name>, one per key, prefixed<erc>.:oauth2.headless.server.client.id,oauth2.headless.server.client.secret,oauth2.token.uri(/o/oauth2/token), plus.audience,.scopes,.authorization.uri,.introspection.uri,.jwks.uri,.redirect.uris,.home.page.uri. A user agent entry getsoauth2.user.agent.client.id,.audience,.scopes, and no secret. The DXP domain and protocol are inroutes/default/dxp(com.liferay.lxc.dxp.mainDomain,com.liferay.lxc.dxp.server.protocol). - Nothing else exposes the secret. The deployed
*.client-extension-config.jsonholds none, andGET /o/oauth2/application?externalReferenceCode=<erc>returns onlyclient_id,homePageURL, andredirectURIs. - In the microservice, point
LIFERAY_ROUTES_CLIENT_EXTENSIONatroutes/default/<project-name>andLIFERAY_ROUTES_DXPatroutes/default/dxp. Read the files at each token request (client_secret_postto the token URI), not once at startup, and on a401read them again and retry once. On LXC the same code works with/etc/liferay/lxc/ext-init-metadataand/etc/liferay/lxc/dxp-metadata(from source and docs, not tested live); Liferay PaaS documents an[ERC]_OAUTH2_HEADLESS_SERVER_CLIENT_SECRETenvironment variable instead.
For manual testing, read the current values without printing them:
ROUTES="bundles/routes/default/<project-name>"
curl \
--data "grant_type=client_credentials" \
--data-urlencode "client_id=$(cat "${ROUTES}/<erc>.oauth2.headless.server.client.id")" \
--data-urlencode "client_secret=$(cat "${ROUTES}/<erc>.oauth2.headless.server.client.secret")" \
--silent \
--url "http://localhost:${PORT}/o/oauth2/token" \
| jq '{token_type, expires_in, scope}'
Call the CET From Browser Code
The steps above authenticate Liferay calling into a CET, or a CET calling back into Liferay. Browser code calling out to a CET is a third case, and Liferay.Util.fetch does not cover it — that carries the user's session cookie, which the CET's own origin will not accept. Use Liferay.OAuth2Client, which exchanges the session for a token against the oAuthApplicationUserAgent entry and attaches it as a Bearer header.
The oAuthApplicationUserAgent entry must already exist; add it per the steps above. The name passed below is that entry's top level key in client-extension.yaml, the same value oAuth2ApplicationExternalReferenceCode takes.
const client = Liferay.OAuth2Client.FromUserAgentApplication(
'<workspace-id>-oauth'
);
const data = await client.fetch('/o/my-service/v1.0/things');
Three behaviors differ from fetch and each one fails in a way that does not name its cause:
-
There are two entry points with different signatures. The global
Liferay.OAuth2Client.FromUserAgentApplicationshown above is synchronous. The identically named export from the@liferay/oauth2-provider-webmodule isasync— it resolves the application profile over HTTP. Miss theawaiton the module form and the next line calls.fetch()on a Promise. -
fetchreturns parsed JSON, not aResponse. On success it returnsresponse.json()when the content type is JSON, and theResponseonly for everything else. Calling.json()on the result throwsTypeError. -
A failed call rejects. There is no
response.okto branch on — a non-2xx rejects with theResponse. Wrap intry/catch, or the failure surfaces as an unhandled rejection.
try {
const data = await client.fetch('/o/my-service/v1.0/things');
}
catch (response) {
console.error(`Request failed: ${response.status}`);
}
The client also refuses any URL outside the application's registered homePageURL. And it mints a token only on an origin that one of the application's redirect URIs starts with; otherwise it rejects with No redirectURI in … matching origin … (OAuth2Client.ts:83–90). Those URIs are not in the YAML. A user agent application gets one per virtual host of the instance, <protocol>://<host>:<port>/o/oauth2/redirect, computed when it is provisioned (OAuth2ProviderApplicationUserAgentConfigurationFactory.java:66–73). So a page served from a host the instance does not list gets no token, for example 127.0.0.1 on an instance whose only virtual host is localhost. To fix it, add the host as a company virtual host with VirtualHostLocalService.updateVirtualHosts(companyId, 0, …), keeping every existing host and the default, then redeploy the CET. The redeployed application then listed both http://127.0.0.1:8680/o/oauth2/redirect and http://localhost:8680/o/oauth2/redirect, and minted tokens from both origins.
Verified on 2026.Q3.5.
Source: js/client/OAuth2Client.ts and js/client/liferay.ts in modules/apps/oauth2-provider/oauth2-provider-web.
Success Signal
After deployment, confirm the OAuth application is registered:
curl \
--silent \
--url "http://localhost:${PORT}/o/headless-admin-user/v1.0/my-user-account" \
--user "test@liferay.com:test" \
| jq '{id, name}'
Then check the OAuth application list in Control Panel → OAuth 2 Administration. The application name <WorkspaceId> OAuth Application should appear with status Active.
To verify the credentials are wired, check the Gogo shell:
telnet localhost 11311
lb | grep <workspace-id>
Both the OAuth application bundle and the CET bundle should show ACTIVE.
Common Errors and Fixes
| Symptom | Check |
|---|---|
| 401 on API call from CET | OAuth entry deployed and ACTIVE; token scope covers the endpoint |
| 401 right after a redeploy, with a token or credentials that worked before | The deploy rotated the client ID and secret: read the routes files again (see "Token Acquisition") |
| 403 on specific resource | Scope too narrow; add the resource's scope string from rules/oauth-scopes.md |
| Application not in Control Panel | Bundle not ACTIVE; run diag <id> in Gogo shell |
| ERC not resolved | ERC field in YAML must match the top level key of the OAuth entry, not its name field |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |