> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# reCAPTCHA

> Kubernetes 배포에서 Google reCAPTCHA로 로그인, 가입 및 비밀번호 재설정을 보호합니다.

**web** 서비스(`login-register` 모듈)는 이메일 로그인, LDAP 로그인, 가입 및 비밀번호 재설정 시 reCAPTCHA v2(invisible)를 요구합니다. 키 생성과 각 설정의 역할은 [reCAPTCHA](https://ayakaleaf-pro.mintlify.site/ko/on-premises/configuration/overleaf-toolkit/authentication/recaptcha.md)를 참고하세요. 이 페이지에서는 이를 Kubernetes에 적용합니다.

| | |
| - | - |
| 서비스 | web, 모든 Ayakaleaf Pro 파드에서 실행. web이 시작될 때 읽음 |
| 파드 → Google | `RECAPTCHA_ENDPOINT`(기본값 `https://www.google.com/recaptcha/api/siteverify`), 검사 대상 요청마다 |
| 브라우저 → Google | `www.recaptcha.net`의 위젯 스크립트 |
| 상태 | Redis의 속도 제한, 암호화된 쿠키에 저장되는 "이 브라우저는 이미 통과함" 기기 기록 |
| 주기적 작업 | 없음 |

### 구성

**1. 사이트 키를 ConfigMap에 넣기**

```yaml theme={null}
  RECAPTCHA_SITE_KEY: <site key>
  # optional
  # RECAPTCHA_ENDPOINT: https://www.recaptcha.net/recaptcha/api/siteverify
  # CAPTCHA_TRUSTED_USERS: robot@example.com
```

사이트 키는 공개 정보입니다. 모든 로그인 페이지에 표시됩니다.

**2. 시크릿 키와 기기 기록 키를 Secret에 넣기**

```bash theme={null}
kubectl -n overleaf patch secret overleaf-secrets --type merge -p '{"stringData":{
  "RECAPTCHA_SECRET_KEY":"<secret key>",
  "DEVICE_HISTORY_SECRET":"'"$(openssl rand -hex 32)"'"}}'
```

두 키를 함께 설정하세요. 사이트 키만 있고 시크릿 키가 없으면 모든 검사가 실패하여 아무도 비밀번호로 로그인하거나 가입하거나 비밀번호를 재설정할 수 없습니다. `DEVICE_HISTORY_SECRET`은 16진수 64자여야 하며, 컨테이너가 이를 생성하지 않습니다.

**3. 적용 및 재시작**

```bash theme={null}
kubectl apply -f 30-config.yaml
kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
```

그런 다음 모든 파드가 엔드포인트에 접근할 수 있는지 확인하세요. 파드는 연결 시도당 약 1초 후에 포기하며, 검사를 수행할 수 없는 로그인은 오류와 함께 실패합니다.

```bash theme={null}
for p in $(kubectl -n overleaf get pod -l app=overleaf -o name); do   # app=overleaf-ha for several replicas
  kubectl -n overleaf exec "$p" -- curl -sS -o /dev/null -w "$p %{http_code}\n" \
    https://www.google.com/recaptcha/api/siteverify
done
```

### 여러 레플리카

모든 레플리카가 `DEVICE_HISTORY_SECRET`을 공유해야 하며, Secret에 넣어 두면 공유됩니다. 값이 서로 다르면 한 레플리카에서 통과한 브라우저가 다른 레플리카에서 다시 캡차를 받게 됩니다. 속도 제한은 모든 레플리카에 걸쳐 Redis에서 집계됩니다.

### Kubernetes에서의 테스트

Google 검증 엔드포인트의 모의 서버(`overleaf-certs`의 `NODE_EXTRA_CA_CERTS`로 신뢰)를 대상으로 한 Kubernetes 1.37 환경에서, reCAPTCHA에 대한 엔드투엔드 테스트(13개 케이스)가 통과했습니다. 레플리카 하나에서 로그인, 가입, 비밀번호 재설정이 각각 캡차가 없거나 실패한 경우 거부되고 통과한 경우 허용되는지, `DEVICE_HISTORY_SECRET`에서 생성된 기기 기록으로 브라우저가 캡차를 건너뛰는지, `CAPTCHA_TRUSTED_USERS`를 검증했고, HAProxy 뒤의 세 레플리카에서는 캡차를 사용한 LDAP 로그인을 검증했습니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.