CAPTCHA YAML Configuration Reference

Liferay DXP 2025.Q3+

You can define a CAPTCHA client extension with a client-extension.yaml file.

Usage Details

This client-extension.yaml file defines a CAPTCHA client extension:

liferay-recaptcha-etc-spring-boot:
    captchaName: reCAPTCHA CX
    captchaResponseParameterName: g-recaptcha-response
    customElementExternalReferenceCode: LXC:liferay-recaptcha-custom-element
    name: Liferay reCAPTCHA Etc Spring Boot
    oAuth2ApplicationExternalReferenceCode: liferay-recaptcha-etc-spring-boot-oaua
    resourcePath: /validation
    type: captcha
liferay-recaptcha-etc-spring-boot-oaua:
    .serviceAddress: localhost:58081
    .serviceScheme: http
    name: Liferay reCAPTCHA Etc Spring Boot OAuth Application User Agent
    type: oAuthApplicationUserAgent

The second block defines the OAuth user agent client extension that oAuth2ApplicationExternalReferenceCode points at. Both blocks live in the same client-extension.yaml file.

The required captchaResponseParameterName property names the request parameter that carries the user’s CAPTCHA response. In this example the value is g-recaptcha-response, the parameter Google’s reCAPTCHA uses. Set it to the parameter name your chosen provider or engine issues. Liferay reads the user’s response from that parameter and sends it to the external application at resourcePath, which validates the response with the provider.

The resourcePath property defines the REST controller’s location, which handles verifying user responses with a CAPTCHA engine or provider. Point to any implementation of a REST controller that’s accessible as an external application (for example, a Java Spring Boot application).

CAPTCHA client extensions require OAuth2 application profiles to secure the validation requests Liferay sends to the client extension’s endpoint. The client-extension.yaml defines an additional OAuth user agent client extension for this profile, and the oAuth2ApplicationExternalReferenceCode property references that client extension’s key value.

The liferay-recaptcha-workspace sample is a working CAPTCHA client extension you can deploy and inspect.

CAPTCHA client extensions also require custom element client extensions to handle the frontend, usually integrating with an external component. The customElementExternalReferenceCode property references that client extension’s key value.

YAML Properties

These properties are specific to CAPTCHA client extensions:

Name	Data Type	Description
`captchaName`	String	(Required) The CAPTCHA engine’s name as it appears in the Instance Settings menu.
`captchaResponseParameterName`	String	(Required) The name of the request parameter that carries the user’s CAPTCHA response.
`customElementExternalReferenceCode`	String	(Required) The external reference code for a custom element client extension, needed for issuing CAPTCHA challenges to users on the frontend.
`oAuth2ApplicationExternalReferenceCode`	String	(Required) The external reference code for an OAuth2 application profile, needed for securing requests.
`resourcePath`	String	(Required) An accessible endpoint of an external application that handles user CAPTCHA responses.
`type`	String	(Required) Must be `captcha` to define a CAPTCHA client extension.