> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 로그인 봇 차단: 크리덴셜 스터핑·무차별 대입 공격 방어

> Didit로 회원가입과 로그인을 봇, 크리덴셜 스터핑, 무차별 대입 공격, 일회용 이메일, 위험 네트워크, 불가능한 이동으로부터 보호하고 공격 모드를 제공합니다.

> [!WARNING]
>
> 인증은 새로 추가된 기능입니다. 보호 기능은 켜기 전까지 꺼져 있습니다. 속도 제한과 코드 입력 시도 횟수 제한은 항상 적용됩니다.

봇 보호는 모든 가입, 로그인 및 비밀번호 재설정에서 실행됩니다. 시도를 여섯 가지 정책과 대조하여 확인합니다. 각 정책에는 모드가 있습니다.

| 모드 | 동작 |
| - | - |
| **꺼짐** | 해당 정책을 확인하지 않습니다. |
| **기록** | 시도가 계속 진행됩니다. `risk_logged` 이벤트에 일치 내용이 기록됩니다. |
| **추가 확인** | 시도가 계속 진행되려면 사용자가 추가 증명을 통과해야 합니다. |
| **차단** | 시도가 `403 {"error": "attempt_blocked"}`와 함께 실패합니다. |

## 보호 설정

인증 관리 API의 `protection/` 경로에 `GET` 및 `PATCH`를 사용하거나 콘솔에서 애플리케이션의 설정을 읽고 변경할 수 있습니다.

```json theme={null}
{
  "enabled": true,
  "breached_password_check": true,
  "policies": {
    "bots": "block",
    "stuffing": "block",
    "brute": "challenge",
    "disposable": "block",
    "vpn": "challenge",
    "travel": "block"
  }
}
```

`enabled`와 `breached_password_check`의 기본값은 `false`입니다. 보호 기능을 켠 후에는 위에 설명된 모드가 기본값으로 적용됩니다.

## 정책

| 정책 | 일치 조건 |
| - | - |
| `bots` | 클라이언트가 0.8 이상의 봇 점수를 보고하거나, 사용자 에이전트가 알려진 헤드리스 또는 자동화된 브라우저인 경우입니다. |
| `stuffing` | 하나의 기기 또는 IP가 15분 이내에 10개 이상의 서로 다른 계정을 시도하거나, 비밀번호가 알려진 유출 비밀번호인 경우입니다. |
| `brute` | 계정에 실패한 시도가 5회 이상 있는 경우입니다. 잘못된 비밀번호와 잘못된 이메일 코드, 전화번호 코드 및 인증 앱 코드가 모두 포함됩니다. |
| `disposable` | 가입 시 일회용 이메일 도메인을 사용하는 경우입니다. |
| `vpn` | IP가 VPN, Tor 또는 데이터센터 네트워크에 속하는 경우입니다. |
| `travel` | 24시간 이내의 로그인이 이전 로그인과 500km를 초과하여 떨어져 있고, 시속 1,000km를 초과하는 경우입니다. |

`vpn` 및 `travel` 정책은 Didit의 IP 분석을 사용합니다. 해당 조회를 사용할 수 없으면 시도는 계속 진행되며, 이 때문에 로그인이 실패하지는 않습니다. `travel`의 위치 정보는 로그인이 완료된 후에만 업데이트됩니다.

### 무차별 대입 및 잠금

`brute` 모드는 5회 실패 후의 동작을 결정합니다.

* **차단**: 사용자는 다시 로그인하기 전에 비밀번호를 재설정해야 합니다.
* **추가 확인**: 계정이 15분 동안 잠기며, 다음 시도에는 추가 증명이 필요합니다.
* **꺼짐** 또는 **기록**: 잠금이 적용되지 않습니다.

무차별 대입 차단 후에도 비밀번호 재설정은 계속 가능하며, 재설정하면 잠금이 해제됩니다. 팀은 콘솔에서 계정 잠금을 직접 해제할 수도 있습니다.

보호 설정을 한 번도 저장하지 않았다면 더 간단한 규칙이 적용됩니다. 비밀번호를 5회 잘못 입력하면 계정이 15분 동안 잠깁니다.

### 봇 점수 및 기기 신호

런타임 호출에 다음 헤더로 기기 신호를 전송하십시오. 호스팅 페이지는 이 신호를 자동으로 전송합니다.

| 헤더 | 내용 |
| - | - |
| `X-Didit-PID` | 지속적인 기기 ID이며, `A-Z a-z 0-9 . _ : -` 문자 8\~128자로 구성됩니다. |
| `X-Didit-FP-Hash` | 기기 지문입니다. |
| `X-Didit-FP-Bot-Score` | 0에서 1 사이의 봇 점수입니다. 해당 범위를 벗어난 값은 무시됩니다. |

이 신호는 판단을 위한 참고 정보일 뿐, 신원을 증명하지는 않습니다. 또한 각 [로그인 이벤트](https://docs.didit.me/ko/authentication/events-and-webhooks.md)와 함께 전달되며, 규칙에서 `event.device.bot_score`를 읽을 수 있습니다.

> [!NOTE]
>
> `AUTOMATION_FRAMEWORK_DETECTED`는 별개의 확인 항목입니다. 이는 **인증 세션**에 대한 [기기 및 IP 분석 경고](https://docs.didit.me/ko/core-technology/ip-analysis/warnings-ip-analysis.md)이며, 인증 SDK가 브라우저 자동화 프레임워크를 보고할 때 발생합니다. 로그인 시에는 실행되지 않습니다. 로그인 시 자동화는 위의 `bots` 정책으로 감지됩니다.

## 추가 확인

추가 확인 대상 시도는 로그인 코드 대신 다음 응답을 반환합니다.

```json theme={null}
{
  "protection_required": true,
  "challenge": "...",
  "methods": ["passkey", "email_code"],
  "options": { "...": "WebAuthn options when a passkey is offered" },
  "expires_in": 300
}
```

`POST protection/complete/`로 완료합니다.

* 사용자 이메일로 전송된 6자리 코드를 사용하는 `{"challenge", "method": "email_code", "code"}`, 또는
* WebAuthn 응답을 사용하는 `{"challenge", "method": "passkey", "response"}`.

5분 이내에 5회 시도할 수 있습니다. 사용자가 사용할 수 있는 증명이 없으면 호출은 `403 {"error": "protection_factor_unavailable"}`를 반환합니다.

## 유출된 비밀번호

`breached_password_check: true`로 설정하면 Didit은 새 비밀번호와 재설정 비밀번호를 알려진 유출 비밀번호와 대조합니다. 비밀번호 자체는 어디에도 전송되지 않습니다. 유출된 비밀번호는 `password_breached`와 함께 거부됩니다. 로그인 시 유출된 비밀번호는 `stuffing` 일치로 간주됩니다. 검사를 사용할 수 없으면 비밀번호가 허용됩니다.

## 공격 모드

진행 중인 공격 시 공격 모드를 켜십시오.

* `POST protection/attack-mode/`에 `{"duration_hours": 1}`(또는 `6` 또는 `24`)을 담아 요청하면 `201`을 반환합니다.
* `DELETE protection/attack-mode/`는 공격 모드를 조기에 종료합니다. 지정된 기간이 지나면 자동으로 종료되기도 합니다.

공격 모드가 켜져 있는 동안에는 다음과 같습니다.

* 모든 가입과 로그인은 **패스키** 추가 확인을 통과해야 합니다. 이메일 코드는 허용되지 않습니다. 새로 가입하는 사용자와 패스키가 없는 사용자는 공격 모드가 종료될 때까지 완료할 수 없습니다.
* VPN, Tor 또는 데이터센터 네트워크에서의 가입은 차단됩니다.

## 속도 제한

모든 런타임 경로는 애플리케이션별, IP별로 제한됩니다.

| 경로 | 분당 | 시간당 |
| - | - | - |
| 디스커버리 및 JWKS | 1,200 | 12,000 |
| 런타임 API 및 호스팅 페이지 | 30 | 300 |
| 이메일 코드, 전화번호 코드 및 제공자 콜백 | 5 | 20 |

제한을 초과하면 호출은 `429`를 반환합니다. `Retry-After` 헤더가 전송되는 경우 이를 따르십시오. 로그인 시도도 분당 제한됩니다. IP당 60회, 계정당 15회, 기기당 30회, 애플리케이션당 3,000회이며, 전화번호 접두사당 SMS 또는 WhatsApp 코드 요청은 20회입니다. 토큰 갱신에는 분당 6,000회의 별도 애플리케이션 버킷이 있으므로, 갱신이 로그인 한도를 소모하지 않습니다.

## 이벤트

각 결정은 [인증 이벤트](https://docs.didit.me/ko/authentication/events-and-webhooks.md)로 기록됩니다. `risk_logged`, `attempt_challenged`, `attempt_blocked`, `challenge_passed`, `challenge_failed`, `attack_mode_started`, `attack_mode_ended`가 있습니다. 이벤트에는 어떤 정책이 일치했는지 표시됩니다.

## 테스트

샌드박스 애플리케이션에서 활성화한 각 모드를 테스트하십시오. 차단된 시도, 통과 및 실패한 추가 확인, 잠금과 그 재설정, 공격 모드의 켜기와 끄기를 확인합니다. 계정 존재 여부가 드러나지 않도록 UI에는 일반적인 오류 메시지를 표시하십시오.


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