---
title: Flarum
---

# Flarum

CaptchaLa 공식 Flarum 확장. 포럼에서 봇이 주로 노리는 액션 — 회원가입, 로그인, 비밀번호 재설정, 게시 — 에 CAPTCHA 검증을 추가하며, 관리자 패널에서 액션 단위의 토글을 제공합니다.

## 보호 대상

아래 항목은 `Admin → Extensions → CaptchaLa`의 개별 토글입니다.

- 회원가입
- 로그인
- 비밀번호 재설정
- 답글 작성
- 새 토론 생성
- 프로필 편집

SSO / Auth Sync 공급자를 통해 인증된 세션은 제외됩니다 — 아래 [SSO / Auth Sync](#sso-auth-sync) 참고.

## 설치

### 1. 확장 추가

Flarum 설치 루트에서 실행:

```bash
composer require captchala/flarum
```

또는 `Admin → Extension Manager`의 **Install** 입력란에 `captchala/flarum`을 붙여넣습니다. 요구 사항: Flarum ≥ 1.8, PHP ≥ 8.1.

### 2. 관리자에서 활성화

`Admin → Extensions`를 열고 **CaptchaLa**를 찾아 **Enable**을 누릅니다.

### 3. 설정

확장의 설정 패널에서:

1. [`dash.captcha.la`](https://dash.captcha.la) 의 **App Key**와 **App Secret**을 붙여넣습니다.
2. 보호할 액션을 활성화합니다.
3. 저장합니다.

## 설정 항목

설정은 Flarum 표준 settings 테이블에 `captchala.*` 접두사로 저장됩니다.

| 설정 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| App Key | string | — | CaptchaLa 대시보드의 공개 키(`cl_pub_…`). 필수. |
| App Secret | string | — | 서버 시크릿. 필수. 서버에서만 `/v1/validate` 호출에 사용. |
| 회원가입 보호 | bool | `true` | 가입 시 챌린지. |
| 로그인 보호 | bool | `false` | 로그인 모달에서 챌린지. 대부분의 포럼은 레이트 리밋으로 로그인을 보호하므로 기본 OFF. |
| 비밀번호 재설정 보호 | bool | `true` | 재설정 메일 요청 시 챌린지. |
| 답글 보호 | bool | `false` | 답글 작성 시 챌린지. 기본 OFF. 스팸 압박이 있을 때 활성화. |
| 새 토론 보호 | bool | `false` | 토론 생성 시 챌린지. |
| 검증 모드 | enum | `popup` | `popup`, `bind`, `embed` 중 하나. Web SDK의 `product` 옵션에 매핑. |
| 테마 | enum | `auto` | `light`, `dark`, 또는 `auto`. |
| 신뢰 사용자 건너뛰기 | bool | `true` | 신뢰 그룹(예: 모더레이터)으로 표시된 사용자는 챌린지를 우회합니다. |

## SSO / Auth Sync

확장은 Flarum 표준 인증 훅(`UserAuthenticated`, 서드파티 Auth Sync 공급자, OAuth 브리지)과 함께 동작합니다.

- SSO 세션으로 인증된 사용자가 접속하면 챌린지가 표시되지 않습니다 — 확장이 해당 세션을 검증된 것으로 간주합니다.
- SSO와 로컬 폼이 혼합된 구성에서는 로컬 폼 경로에서만 챌린지가 실행됩니다.
- 「신뢰 사용자 건너뛰기」 토글은 이 위에 중첩됩니다 — 로컬 로그인이라도 신뢰 그룹은 챌린지를 우회합니다.

## FAQ

**확장은 무료인가요?**

네. Composer 패키지 자체는 무료입니다. CaptchaLa 무료 플랜은 월 1,000회 검증을 포함합니다.

**스팸 가입을 막을 수 있나요?**

대부분의 자동화된 가입은 첫 리스크 스코어에서 챌린지되거나 차단됩니다. 어떤 CAPTCHA도 100%를 막을 수는 없습니다 — 다만 테스트 포럼에서는 활성화 후 스팸 가입량이 대략 한 자릿수 감소했습니다.

**가입에만 적용할 수 있나요?**

가능합니다. 각 액션은 개별 토글입니다. 기본 프로필은 회원가입과 비밀번호 재설정만 활성화합니다.

**SSO / Auth Sync에서 동작하나요?**

동작합니다. SSO / Auth Sync 공급자로 열린 세션은 챌린지를 건너뜁니다. [SSO / Auth Sync](#sso-auth-sync) 참고.

**오픈소스인가요?**

네 — PHP 확장 코드는 오픈소스이며, 검증 호출은 호스팅되는 CaptchaLa 서비스로 이루어집니다.

## 소스

- 확장 저장소: [`github.com/Captcha-La/captchala-flarum`](https://github.com/Captcha-La/captchala-flarum)
- Packagist: [`captchala/flarum`](https://packagist.org/packages/captchala/flarum)
- 관련 문서: [Web SDK](/ko/web-sdk) · [PHP 서버 SDK](/ko/sdk/server-php) · [API 레퍼런스](/ko/api-reference)