Captcha
Captcha 플러그인은 주요 엔드포인트에 캡차 확인을 추가하여 Better Auth 시스템에 봇 보호를 통합합니다. 이 플러그인은 사람 사용자만 가입, 로그인 또는 비밀번호 재설정과 같은 작업을 수행할 수 있도록 보장합니다. 다음 제공업체가 현재 지원됩니다:
이 플러그인은 이메일 & 비밀번호 인증과 함께 즉시 작동합니다. 다른 인증 방법과 함께 사용하려면 플러그인 옵션에서 endpoints 배열을 구성해야 합니다.
설치
auth 설정에 플러그인 추가
import { betterAuth } from "better-auth";
import { captcha } from "better-auth/plugins";
export const auth = betterAuth({
plugins: [
captcha({
provider: "cloudflare-turnstile", // 또는 google-recaptcha, hcaptcha, captchafox
secretKey: process.env.TURNSTILE_SECRET_KEY!,
}),
],
});요청 헤더에 캡차 토큰 추가
보호된 모든 엔드포인트에 대한 요청 헤더에 캡차 토큰을 추가합니다. 이 예제는 signIn 요청에 포함하는 방법을 보여줍니다:
await authClient.signIn.email({
email: "user@example.com",
password: "secure-password",
fetchOptions: {
headers: {
"x-captcha-response": turnstileToken,
"x-captcha-user-remote-ip": userIp, // 선택 사항: 사용자의 IP 주소를 캡차 서비스로 전달
},
},
});- 클라이언트 측에서 Cloudflare Turnstile을 구현하려면 공식 Cloudflare Turnstile 문서를 따르거나 react-turnstile과 같은 라이브러리를 사용하세요.
- 클라이언트 측에서 Google reCAPTCHA를 구현하려면 공식 Google reCAPTCHA 문서를 따르거나 react-google-recaptcha (v2) 및 react-google-recaptcha-v3 (v3)와 같은 라이브러리를 사용하세요.
- 클라이언트 측에서 hCaptcha를 구현하려면 공식 hCaptcha 문서를 따르거나 @hcaptcha/react-hcaptcha와 같은 라이브러리를 사용하세요.
- 클라이언트 측에서 CaptchaFox를 구현하려면 공식 CaptchaFox 문서를 따르거나 @captchafox/react와 같은 라이브러리를 사용하세요.
작동 방식
플러그인은 미들웨어로 작동합니다: 구성된 엔드포인트에 대한 모든 POST 요청을 가로챕니다(플러그인 옵션 섹션의 endpoints 참조).
캡차 제공업체의 /siteverify를 호출하여 서버에서 캡차 토큰을 검증합니다.
- 토큰이 누락되었거나 캡차 제공업체에서 거부되었거나
/siteverify엔드포인트를 사용할 수 없는 경우, 플러그인은 오류를 반환하고 요청을 중단합니다. - 토큰이 캡차 제공업체에서 수락되면 미들웨어는
undefined를 반환하여 요청이 계속 진행될 수 있음을 의미합니다.
플러그인 옵션
provider(필수): 캡차 제공업체secretKey(필수): 서버 측 검증에 사용되는 제공업체의 비밀 키endpoints(선택 사항): 캡차 검증이 강제되는 경로의 기본 배열을 재정의합니다. 기본값은:["/sign-up/email", "/sign-in/email", "/forget-password",].minScore(선택 사항 - Google ReCAPTCHA v3만 해당): 최소 점수 임계값. 기본값은0.5.siteKey(선택 사항 - hCaptcha 및 CaptchaFox만 해당): 한 사이트키에서 발급된 토큰이 다른 곳에서 사용되는 것을 방지합니다.siteVerifyURLOverride(선택 사항): 캡차 확인 요청의 엔드포인트 URL을 재정의합니다.