<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
<title>AJ Security/Google Recaptcha</title>
<meta name="description" content="A Practical Java Web Security Library. Google Recaptcha"/>
<meta name="keywords" content="security, xss, csrf, captcha, Google Recaptcha"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<link rel="stylesheet" href="https://framework.ajaxjs.com/static/font/font.css" />
<link rel="stylesheet" href="/asset/main.css"/>
<link rel="icon" type="image/x-icon" href="https://framework.ajaxjs.com/aj-logo/logo.ico"/>
<script src="https://framework.ajaxjs.com/static/aj-docs/common.js"></script>
<script>
var userLang = navigator.language || navigator.userLanguage;
if (userLang.startsWith('zh') && location.pathname.indexOf('cn') == -1) {
confirm('欢迎！您可以改为访问中文内容。是否继续？') && location.assign('/cn');
}
var _hmt = _hmt || [];
(function() {
var hm = document.createElement("script");
hm.src = "https://hm.baidu.com/hm.js?950ba5ba1f1fe4906c3b4cf836080f03";
var s = document.getElementsByTagName("script")[0];
s.parentNode.insertBefore(hm, s);
})();
</script>
</head>
<body>
<nav>
<div>
<div class="links">
<a href="/">🏠 Home</a>
| ⚙️ Source:
<a target="_blank" href="https://github.com/lightweight-component/aj-security">Github</a>/<a target="_blank" href="https://gitcode.com/lightweight-component/aj-security">Gitcode</a>
|
<a href="/cn">Chinese Version</a>
</div>
<h1><img src="https://framework.ajaxjs.com/aj-logo/logo.png" style="vertical-align: middle;height: 45px;margin-bottom: 6px;" /> AJ Security</h1>
<h3>User Manual</h3>
</div>
</nav>
<div>
<menu>
<ul>
<li class="selected">
<a href="/">Home</a>
</li>
<li>
<a href="/install">Installation & Configuration</a>
</li>
</ul>
<h3>HTTP Web Security</h3>
<ul>
<li>
<a href="/http/http-referer">HTTP Referer Validation</a>
</li>
<li>
<a href="/http/timestamp">Timestamp Encrypted Token Validation</a>
</li>
<li>
<a href="/http/paramssign">Parameter Signature</a>
</li>
<li>
<a href="/http/ip-list">IP Whitelist/Blacklist</a>
</li>
<li>
<a href="/http/nonrepeatsubmit">Prevent Duplicate Submission</a>
</li>
</ul>
<h3>General Web Validation</h3>
<ul>
<li>
<a href="/classic/xss">Prevent XSS Attacks</a>
</li>
<li>
<a href="/classic/crlf">Prevent CRLF Attacks</a>
</li>
</ul>
<h3>Captcha Mechanism</h3>
<ul>
<li><a href="/captcha/img-captcha">Image Captcha</a></li>
<li><a href="/captcha/google">Google-based Captcha</a></li>
<li><a href="/captcha/cf">CloudFlare-based Captcha</a></li>
</ul>
<h3>HTTP Standard Authentication</h3>
<ul>
<li><a href="/auth/http-basic-auth">HTTP Basic Auth</a></li>
<li><a href="/auth/http-digest-auth">HTTP Digest Auth</a></li>
</ul>
<h3>API Features</h3>
<ul>
<li><a href="/api/limit">Rate Limiting</a></li>
</ul>
<h3>Other Practical Features</h3>
<ul>
<li><a href="/misc/desensitize">Field Desensitization</a></li>
<li><a href="/misc/encryption-api">API Encryption</a></li>
<li><a href="/misc/trace-id">Trace Tracking</a></li>
</ul>
</menu>
<article>
<h1>Google reCAPTCHA</h1>
<p>We have encapsulated the Google reCAPTCHA verification for easier use. reCAPTCHA v3 is powerful and eliminates user interaction, enabling seamless and invisible verification.</p>
<h2>Preparation</h2>
<p>You need a Google account to register at <a href="https://www.google.com/recaptcha/admin">https://www.google.com/recaptcha/admin</a>. We will be using <strong>reCAPTCHA v3</strong>.</p>
<p><img src="/captcha/413153c9f85df5e54d02b1401f3da4de.png" alt=""></p>
<p>Fill in your domain name. Tips:</p>
<ol>
<li>You can place multiple domains under one site (in reality, even different sites are fine).</li>
<li>Add <code>localhost</code> to make local development and testing easier.</li>
</ol>
<p>Finally, obtain your <strong>site key (appId)</strong> and <strong>secret key</strong>.</p>
<p><img src="/captcha/1.jpg" alt=""></p>
<h1>Usage</h1>
<p>We use a custom implementation.</p>
<h2>Include the Script</h2>
<pre><code class="language-html"><!-- Google anti-bot verification -->
<style>.grecaptcha-badge{display: none;}</style>
<script src="https://www.recaptcha.net/recaptcha/api.js?render=XXXX"></script>
</code></pre>
<p>The <code>render</code> parameter is your <strong>site key</strong>, not the secret key. The included CSS style hides the Google badge — most users won’t want to see it.</p>
<p><img src="/captcha/164f43cd827274a704fa4002b62dc529.png" alt=""></p>
<h2>Frontend</h2>
<p>Usually, any form that triggers a write operation should include reCAPTCHA validation. We fetch the token before submitting the form and pass it to the backend as a parameter. Below is an example of a standard form submission.</p>
<pre><code class="language-html"><script src="https://www.recaptcha.net/recaptcha/api.js?render=6LclfLMZAAAAAKC3YUTP4E3Ylc0PSvfXpneRePAH"></script>
<form id="myForm" action="http://localhost:8083/foo/captcha_google" method="POST">
<input type="text" name="name" />
<br />
<input type="text" name="age" />
<br />
<input type="hidden" name="grecaptchaToken" id="recaptchaToken" />
<button type="submit">Submit</button>
<p id="status"></p>
</form>
<script>
document.getElementById('myForm').addEventListener('submit', function (e) {
debugger
e.preventDefault(); // Prevent default form submission
const form = e.target;
const tokenInput = document.getElementById('recaptchaToken');
grecaptcha.ready(function () {
grecaptcha.execute('6LclfLMZAAAAAKC3YUTP4E3Ylc0PSvfnp8eRePAH', { action: 'submit' }).then(function (token) {
debugger
tokenInput.value = token; // Set token value in hidden input
form.submit(); // Now submit the form
});
});
});
</script>
</code></pre>
<p>Update the <code>site key</code> accordingly.</p>
<h3>Example Using POST JSON Raw Body</h3>
<pre><code class="language-javascript">document.getElementById('myForm').addEventListener('submit', function (e) {
e.preventDefault();
const form = e.target;
const status = document.getElementById('status');
// Execute reCAPTCHA
grecaptcha.ready(function () {
grecaptcha.execute('6LclfLMZAAAAAKC3YUTP4Ylc0PSvfnpneRePAH', { action: 'submit' }).then(function (token) {
// Add token to form data
const formData = new FormData(form);
formData.append('token', token);
// Submit form via fetch
fetch('/api/submit-form', {
method: 'POST',
body: JSON.stringify(Object.fromEntries(formData)),
headers: {
'Content-Type': 'application/json'
}
}).then(response => response.json()).then(data => {
status.textContent = data.message || 'Success!';
status.style.color = 'green';
form.reset();
}).catch(error => {
status.textContent = 'An error occurred.';
status.style.color = 'red';
console.error('Error:', error);
});
});
});
});
</code></pre>
<h2>Backend Handling</h2>
<p>The backend logic involves sending the received [token](file://d:\sp42\code\zhongen-rdd\ui\src\api\user\index.ts#L29-L29) to Google for verification.</p>
<h3>YAML Configuration</h3>
<p>Add the following configuration to your <code>application.yml</code> file:</p>
<pre><code class="language-yaml">security:
captcha:
google:
enabled: true
globalCheck: false # Global check
accessSecret: 6LclfLMZAAAAAD6XUpBL0qHKYWijay7-lGpOf
</code></pre>
<h3>Intercept and Validate</h3>
<p>Add the <code>@GoogleCaptchaCheck</code> annotation to the relevant interface:</p>
<pre><code class="language-java">@PostMapping("/captcha_google")
@GoogleCaptchaCheck
boolean google(@RequestParam(GoogleCaptcha.PARAM_NAME) String token, @ModelAttribute User user);
</code></pre>
<p>Once verified successfully, you'll get a result like this:</p>
<p><img src="/captcha/d20ef7798177009e31b7125122736d5f.png" alt=""></p>
</article>
</div>
<footer>
AJ Security, a part of
<a href="https://framework.ajaxjs.com" target="_blank">AJ-Framework</a>
open source. Mail:frank@ajaxjs.com, visit
<a href="https://blog.csdn.net/zhangxin09" target="_blank">my blog(In Chinese)</a>. <br/> <br/> Copyright © 2025 Frank Cheung. All rights reserved.
</footer>
</body>
</html>
