CAPTCHAクライアント拡張機能の使用
Liferay DXP 2025年第3四半期以降
CAPTCHA チャレンジは、サイトを攻撃しているボットや悪意のあるコードではなく、人間のユーザーがアクセスしていることを確認するために Web サイトで使用されます。 Liferay は、 SimpleCaptcha と Google の reCAPTCHAの 2 つの CAPTCHA エンジン構成をすぐに使用できます。
別のサードパーティ CAPTCHA プロバイダーを統合する場合は、CAPTCHA クライアント拡張機能を使用する必要があります。 この例では、Google の reCAPTCHA を再実装し、代替プロバイダー向けにどのような詳細を変更することが重要であるかを把握できるようにします。
ここで使用される CAPTCHA クライアント拡張機能の例には、安全ではないサイトと秘密キーの値が含まれており、常に成功応答が返されます。 これらのキーを独自のキーに置き換えずに、クライアント拡張機能を本番インスタンスにデプロイしないでください。
前提条件
このクライアント拡張機能の使用を開始するには、
-
サポートされているバージョンの Javaをインストールします。
-
liferay-portalリポジトリをクローンします。git clone https://github.com/liferay/liferay-portal.gitまたは、 GitHub のリポジトリ に移動し、 コード → ZIP のダウンロードをクリックして、
.zipファイルでリポジトリをダウンロードすることもできます。
liferay-portal コード リポジトリ内の workspaces/liferay-recaptcha-workspace/ フォルダは、必要なクライアント拡張機能を備えた自己完結型のワークスペースです。
liferay-portal リポジトリには、 workspaces/liferay-hcaptcha-workspace/ フォルダ内に hCaptcha 実装 も含まれています。 このワークスペースのクライアント拡張機能を workspaces/liferay-recaptcha-workspace/ のクライアント拡張機能と比較すると、調整すべき構成についてさらに詳しく知ることができます。
クライアント拡張の検討
ダウンロードしたプロジェクトには、CAPTCHA クライアント拡張機能と、UI に必要な カスタム要素 クライアント拡張機能の 2 つのクライアント拡張機能が含まれています。
CAPTCHA クライアント拡張機能を実装する場合は、選択した CAPTCHA プロバイダーの指示に従って、実装のさまざまな部分を変更します。 このプロセスには、 サイト キー (CAPTCHA プロバイダーを使用して Web サイトの UI コンポーネントを認証するため) と 秘密キー (プロバイダーを使用してコード バックエンドを認証するため) の生成が含まれます。
ここでは、調整できる CAPTCHA クライアント拡張機能 (およびペアになったカスタム要素) の最も重要な部分を示します。
クライアント拡張YAML構成
CAPTCHA クライアント拡張機能は、 client-extensions/liferay-recaptcha-etc-spring-boot/ フォルダにあります。 client-extension.yaml ファイルに定義されています。
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-oauth-application-user-agent
resourcePath: /validation
type: captcha
このブロックには、クライアント拡張機能の ID (liferay-recaptcha-etc-spring-boot) と Liferay の UI に表示される名前 (reCAPTCHA CX) が含まれます。 また、正常に動作するために必要な他の 2 つのクライアント拡張機能も参照します。 カスタム要素クライアント拡張機能 (LXC:liferay-recaptcha-custom-element) と OAuth 2 ユーザー エージェント クライアント拡張機能です。
captchaResponseParameterName は、ユーザーの応答を検証するために必要です。 Google の reCAPTCHA は、 g-recaptcha-response POST パラメータを使用します。 選択した CAPTCHA プロバイダーに応じて、この値を適切な応答パラメータ名に設定します。
悪意のあるクライアント拡張機能は、関連のないパラメータ名を使用して、Liferay のサーバー応答から安全でない詳細を抽出する可能性があります。 構成を慎重に確認し、CAPTCHA 応答パラメータのみが使用されていることを確認してください。
resourcePath は、ユーザーがチャレンジを完了したときに CAPTCHA 応答が送信される場所を指定します。 このクライアント拡張の例では、Spring Boot アプリケーションは /validation パスで応答を受信し、Google の API で検証します。
これらの構成の下にある別のブロックでは、CAPTCHA クライアント拡張プロジェクトにバンドルされている OAuth ユーザー エージェント クライアント拡張 が定義されています。 このクライアント拡張は、バックエンド サーバーが Liferay と安全に通信するために必要です。
liferay-recaptcha-etc-spring-boot-oauth-application-user-agent:
.serviceAddress: localhost:58081
.serviceScheme: http
name: Liferay reCAPTCHA Etc Spring Boot OAuth Application User Agent
type: oAuthApplicationUserAgent
サーバーのプロパティ
src/main/resources/application-default.properties ファイルにもいくつかの重要な設定が含まれています。
liferay.recaptcha.secret=[secret value]
#
# OAuth
#
liferay.oauth.application.external.reference.codes=liferay-recaptcha-etc-spring-boot-oauth-application-user-agent
#
# Spring Boot
#
server.port=58081
このプロジェクトに含まれる秘密鍵の値は、教育目的で公開されています。 この秘密キー値 (および カスタム要素のサイト キー値) を置き換えるときは、値を保護されたままにしておいてください。
liferay.recaptcha.secret プロパティは、Spring Boot サーバーが CAPTCHA プロバイダーと通信してユーザーの応答を検証することを許可します。 秘密の値を、選択したプロバイダーからの新しい秘密キーに置き換えます。
liferay.oauth.application.external.reference.codes 値は、 client-extension.yaml ファイルで設定されている OAuth ユーザーエージェントクライアント拡張機能を参照します。
Spring Boot サーバーの実装
ユーザーがチャレンジを完了すると、CAPTCHA クライアント拡張機能はコードを実行してユーザーの応答を受信し、サードパーティ プロバイダーで検証する必要があります。 アクセス可能なエンドポイントを使用する限り、任意のサーバー フレームワークを使用してバックエンドを実装できます。 この例では、バックエンド コードは Spring Boot アプリケーションとして実装されています。
Spring Boot 実装で最も重要なファイルは src/main/java/com/liferay/recaptcha/ValidationRestController.javaです。 このファイルでは、REST コントローラーが /validation エンドポイント ( resourcePath YAML プロパティで構成されているものと同じ) でリクエストを処理していることに注意してください。
@RequestMapping("/validation")
@RestController
public class ValidationRestController extends BaseRestController {
post メソッドには重要な実装の詳細が含まれています。 まず、ユーザーの応答 (および 秘密鍵) をパッケージ化する JSON オブジェクトを生成し、それを CAPTCHA プロバイダーに送信します。
JSONObject responseJSONObject = new JSONObject();
MultiValueMap<String, String> body = new LinkedMultiValueMap<>();
JSONObject jsonObject = new JSONObject(json);
body.add("remoteip", jsonObject.getString("remoteip"));
body.add("response", jsonObject.getString("response"));
body.add("secret", _secret);
HttpHeaders httpHeaders = new HttpHeaders();
httpHeaders.setContentType(MediaType.APPLICATION_FORM_URLENCODED);
次に、ハードコードされた検証 URL を使用して CAPTCHA プロバイダー (この例では、Google の reCAPTCHA) に応答を送信し、返される ResponseEntity に基づいて成功を検証します。
ResponseEntity<String> responseEntity = _restTemplate.postForEntity(
"https://www.google.com/recaptcha/api/siteverify",
new HttpEntity<>(body, httpHeaders), String.class);
応答が再度送り返される場合、Liferay では success パラメータを true または falseに設定することのみが必要です。
CAPTCHA プロバイダーの指示を確認して、変更する必要がある詳細 (特定の応答パラメータや検証 URL など) を判断します。
カスタム要素
CAPTCHA クライアント拡張サーバーは CAPTCHA 応答のバックエンド検証を処理しますが、ユーザーが CAPTCHA チャレンジを完了するためのフロントエンド インターフェイスも必要です。 別のカスタム要素クライアント拡張機能が Liferay でのユーザー操作を処理し、CAPTCHA プロバイダーの UI コンポーネントと統合されます。
この例では、カスタム要素は client-extensions/liferay-recaptcha-custom-element/ フォルダに実装されており、Google の reCAPTCHA によって提供されるコンポーネントを使用しています。 ここでのコンポーネントは Reactを使用して組み込まれていますが、任意のフロントエンド フレームワークを使用して、選択したプロバイダーと統合できます。
このプロジェクト フォルダの src/components/Captcha.js ファイルには、Google が提供するコンポーネントを使用した次の実装が含まれています。
import React from 'react';
import ReCAPTCHA from 'react-google-recaptcha';
const Captcha = () => {
return (
<div>
<ReCAPTCHA sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI" />
</div>
);
};
export default Captcha;
ReCAPTCHA 要素内の sitekey 値により、Web サイト上のコンポーネントはプロバイダーから CAPTCHA チャレンジを受信できるようになります。 このコンポーネントを、選択したプロバイダーのコンポーネントに置き換え、この例のテスト API キーを、生成した新しいキーに置き換えます。
カスタム要素クライアント拡張の詳細については、 カスタム要素タイプの使用 を参照してください。
マイクロサービスを開始する
client-extensions/liferay-recaptcha-etc-spring-boot/ フォルダから、
../../gradlew bootRun
Spring Boot アプリケーションが起動し、ログにメッセージが出力されます。
2025-08-26T08:42:31.470-07:00 INFO 31799 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port 58081 (http) with context path '/'
2025-08-26T08:42:31.475-07:00 INFO 31799 --- [ main] c.l.r.RecaptchaSpringBootApplication : Started RecaptchaSpringBootApplication in 1.635 seconds (process running for 1.87)
<==========---> 80% EXECUTING [2m 33s]
Liferayにクライアント拡張機能をデプロイする
新しいLiferay インスタンスを起動し、以下を実行します。
docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.132-ga132
http://localhost:8080でLiferayにサインインします。 メールアドレス test@liferay.com とパスワード testを使用してください。 プロンプトが表示されたら、パスワードを learnに変更します。
Liferay が起動したら、 client-extensions/ フォルダから次のコマンドを実行して、両方のクライアント拡張機能をデプロイします。
../../gradlew clean deploy -Ddeploy.docker.container.id=$(docker ps -lq)
これにより、両方のクライアント拡張機能がビルドされ、zip ファイルが Liferay の deploy/ フォルダにデプロイされます。
クライアント拡張機能をLiferay SaaSにデプロイするには、Liferay Cloud コマンドラインツール を使用して lcp deployを実行します。
Liferay インスタンスのコンソールで両方のクライアント拡張機能のデプロイメントを確認します。
STARTED liferayrecaptchacustomelement_7.4.3.137
STARTED liferayrecaptchaetcspringboot_7.4.3.137
クライアント拡張機能がデプロイされたので、CAPTCHA サービスを使用するように Liferay を設定します。
クライアント拡張機能を使用するようにLiferayを設定する
-
Liferay インスタンスにログインします。
-
コントロール パネル → インスタンス設定に移動します。
-
[セキュリティ] の下で、 [セキュリティ ツール]をクリックします。
-
サイドバーで CAPTCHA が選択されていることを確認し、CAPTCHA エンジン ドロップダウン メニューで reCAPTCHA CX を選択します。
重要ここで CAPTCHA エンジンを設定すると、インスタンス全体で使用される CAPTCHA が置き換えられます (例: アカウントの作成 ページや パスワードを忘れた場合 ページなど)。
-
アカウントからログアウトします。
-
再度ログインを開始し、 パスワードを忘れた場合をクリックします。
新しい CAPTCHA は、「パスワードを忘れた場合」ページの入力フィールドの下に表示されます。 サイト キーを置き換えなかった場合は、CAPTCHA 入力にも赤い警告メッセージが表示されます。
今後の流れ
Liferay で CAPTCHA クライアント拡張機能を正常に使用できました。 次に、他の CAPTCHA エンジン ( liferay-hcaptcha-workspace の例など) を調べて、この例の実装の詳細を置き換えてみてください。
他のクライアント拡張機能タイプを展開してみることもできます。
機能の可用性の概要
| Liferayのバージョン | 機能のステータス | 機能フラグラベル |
|---|---|---|
| ライフレイ DXP 2025年第3四半期 | リリース | CAPTCHA クライアント拡張 (LPD-36464) |
| ライフレイ DXP 2025年第4四半期 | Googleアナリティクス | - |