reCAPTCHA Enterprise 사용 설정

이 문서에서는 Identity Platform을 reCAPTCHA와 통합하여 사용자의 보안을 강화하는 방법에 대해 설명합니다. 이 기능을 사용하면 스팸, 악용, 기타 허위 행위에 대한 앱의 복원력이 우수해집니다.

Identity Platform과 reCAPTCHA를 통합하면 사용자 요청을 검증하기 위해 사용자를 대신하여 reCAPTCHA 평가가 생성됩니다. 가격 책정 관련 정보는 reCAPTCHA 가격 책정을 참조하세요.

개요

Identity Platform 통합을 reCAPTCHA와 구성하면 Identity Platform이 프로젝트에서 점수 기반 reCAPTCHA 사이트 키를 자동으로 프로비저닝합니다. 사용자가 다음 작업을 사용하여 앱이나 사이트에 액세스하면 클라이언트 SDK가 reCAPTCHA를 로드합니다.

작업	메서드
이메일 및 비밀번호 로그인	`signInWithPassword`
이메일 및 비밀번호 가입	`signUpPassword`
이메일 링크 로그인	`getOobCode`
비밀번호 재설정	`getOobCode`

그러면 reCAPTCHA는 Identity Platform에 구성 및 위험 허용 범위를 기준으로 요청의 위험을 평가하는 위험 신호를 제공합니다.

자세한 내용은 reCAPTCHA Enterprise 개요를 참조하세요.

시작하기 전에

사용자의 이메일 로그인을 구성하세요.

서비스 계정 만들기

reCAPTCHA를 사용 설정하기 전에 reCAPTCHA를 사용할 각 프로젝트의 서비스 계정을 만들고 각 서비스 계정에 reCAPTCHA에 대한 액세스 권한을 부여해야 합니다. 이렇게 하면 Identity Platform이 reCAPTCHA 키를 자동으로 관리할 수 있습니다.

서비스 계정을 만들려면 다음을 수행합니다.

Google Cloud CLI를 사용하여 서비스 계정을 만듭니다.

gcloud beta services identity create \
    --service=identitytoolkit.googleapis.com \
    --project=PROJECT_ID

PROJECT_ID를 해당 프로젝트의 ID로 바꿉니다.

서비스 계정에 reCAPTCHA에 대한 액세스 권한을 부여합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-identitytoolkit.iam.gserviceaccount.com \
    --role=roles/identitytoolkit.serviceAgent

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID
PROJECT_NUMBER: 프로젝트 계정 번호

reCAPTCHA 사용 설정

reCAPTCHA에는 사용자를 보호하는 데 도움이 되는 두 가지 모드가 있습니다.

감사(Audit): 사용 설정하면 Identity Platform이 요청을 차단하지 않고 Identity Platform API에 대한 트래픽을 평가하는 데 사용되는 reCAPTCHA 키를 프로젝트에 하나 이상 만듭니다. 감사 모드 중에 내보낸 측정항목을 사용하여 reCAPTCHA 시행을 사용 설정해야 하는지 확인하세요.
시행(Enforcement): Identity Platform이 사용 설정되면 Identity Platform API에 대한 트래픽을 평가하는 데 사용되는 reCAPTCHA 키가 프로젝트에 하나 이상 생성됩니다. reCAPTCHA 토큰이 포함되지 않은 API 요청은 거부됩니다. reCAPTCHA를 지원하는 모든 클라이언트를 SDK로 마이그레이션한 후에만 시행을 사용 설정하세요.

reCAPTCHA를 사용 설정하려면 다음을 수행하세요.

아직 설정하지 않았다면 프로젝트에서 reCAPTCHA API를 사용 설정합니다.

Admin SDK를 사용하여 프로젝트에 Identity Platform과 reCAPTCHA 통합을 사용 설정합니다. reCAPTCHA 지원은 Node.js Admin SDK 버전 11.7.0 이상에서 제공됩니다.

예를 들면 다음과 같습니다.

// Get project config
const getProjectConfig = () => {
  getAuth().projectConfigManager().getProjectConfig()
  .then((response) => {
    console.log('Project reCAPTCHA config: ', response.recaptchaConfig);
  }).catch((error) => {
    console.log('Error getting project config:', error);
  });
}

// Update project config with reCAPTCHA config
const updateConfigRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'AUDIT',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};
const updateProjectConfigWithRecaptcha = () => {
  getAuth().projectConfigManager().updateProjectConfig(updateConfigRequest).then((response) => {
    console.log('Updated reCAPTCHA config for project: ', response.recaptchaConfig);
  }).catch((error) => {
    console.log('Error updating project config:', error);
  });
}

Admin SDK를 사용하여 테넌트의 reCAPTCHA와 Identity Platform 통합을 사용 설정합니다. 예를 들면 다음과 같습니다.

// Update tenant with reCAPTCHA config
const updateTenantRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'AUDIT',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};
const updateTenantWithRecaptchaConfig = () => {
  getAuth().tenantManager().updateTenant("TENANT_ID", updateTenantRequest)
  .then((response) => {
    console.log('Updated reCAPTCHA config for tenant: ', response.recaptchaConfig);
  }).catch((error) => {
    console.log('Error updating the tenant:', error);
  });
}

다음을 바꿉니다.

TENANT_ID: 테넌트 ID

Apple 플랫폼 또는 Android에서 Identity Platform을 사용하는 경우 Firebase Console에서 앱을 등록해야 합니다.
- Apple 플랫폼의 경우 Identity Platform을 사용하는 각 번들 ID를 등록합니다.
- Android의 경우 Identity Platform을 사용하는 각 Android 패키지 이름을 등록합니다.
웹에서 Identity Platform을 사용하는 경우 reCAPTCHA를 사용하는 각 도메인에 승인된 도메인을 추가해야 합니다. 승인된 도메인을 추가하려면 다음을 수행합니다.
1. Google Cloud 콘솔에서 Identity Platform 페이지로 이동합니다.
  
  Identity Platform으로 이동
2. 설정 > 보안으로 이동합니다.
3. 도메인 추가를 클릭합니다.
4. 도메인 이름을 입력하고 추가를 클릭하여 도메인을 저장합니다.
사이트 키 프로비저닝을 완료하는 데 몇 분 정도 걸릴 수 있습니다. 흐름이 보호되는지 확인하려면 측정항목을 확인하세요.

클라이언트 SDK 구성

앱의 플랫폼에 따라 클라이언트 SDK를 구성합니다.

웹

최신 버전의 웹 SDK로 업데이트하세요. reCAPTCHA 지원은 JavaScript SDK 버전 9.20.0 이상에서 제공됩니다. 웹 SDK를 앱에 통합하면 reCAPTCHA 구성을 자동으로 가져오고 구성한 제공업체를 보호합니다.

SDK의 네트워크 호출 수를 줄이고 reCAPTCHA 신호 수집을 개선하려면 다음과 같이 명시적으로 구성하는 것이 좋습니다.

import { initializeRecaptchaConfig } from '@firebase/auth';

// Initialize Firebase Auth
const auth = getAuth();
initializeRecaptchaConfig(auth)
  .then(() => {
    console.log("Recaptcha Enterprise Config Initialization successful.")
  })
  .catch((error) => {
    console.error("Recaptcha Enterprise Config Initialization failed with " + error)
  });

Android

Android SDK 버전 31.5.0 이상으로 업데이트합니다. reCAPTCHA 지원에는 API 수준 19(Cassandra) 이상 및 Android 4.4 이상이 필요합니다. Android SDK를 앱과 통합하면 reCAPTCHA 구성을 자동으로 가져오고 구성한 제공업체를 보호합니다.
앱 수준 build.gradle 파일의 종속 항목 섹션에 다음 빌드 규칙을 추가하세요.
```
implementation 'com.google.android.recaptcha:recaptcha:18.4.0'
```
reCAPTCHA SDK 버전 18.4.0 이상을 사용해야 합니다.

SDK의 네트워크 호출 수를 줄이고 reCAPTCHA 신호 수집을 보다 효과적으로 수행하려면 다음과 같이 명시적으로 구성하는 것이 좋습니다.

Kotlin:

// Initialize Firebase Auth
auth = Firebase.auth

auth.initializeRecaptchaConfig().addOnCompleteListener(this) { task ->
    if (task.isSuccessful) {
        Log.d(TAG, "Recaptcha Enterprise Initialization successful.")
    } else {
        Log.w(TAG, "Recaptcha Enterprise Initialization failed.")
    }
}

자바

// Initialize Firebase Auth
auth = FirebaseAuth.getInstance();
auth.initializeRecaptchaConfig().addOnCompleteListener(
  this, new OnCompleteListener<void>() {
  @Override
  public void onComplete(@NonNull Task<void> task) {
    if (task.isSuccessful()) {
      Log.d(TAG, "Recaptcha Enterprise Initialization successful.");
    } else {
      Log.w(TAG, "Recaptcha Enterprise Initialization failed.");
    }
  }
});

iOS

iOS SDK 버전 10.14.0 이상으로 업데이트합니다. iOS SDK를 앱과 통합하면 reCAPTCHA 구성을 자동으로 가져오고 구성한 제공업체를 보호합니다.
앱에 reCAPTCHA iOS SDK를 통합하려면 환경 준비를 참조하세요.
링커 플래그에 -ObjC가 있는지 확인하려면 타겟 > 빌드 설정 > 전체 > 연결로 이동하여 Other Linker Flags에 -ObjC가 표시되는지 확인합니다.

SDK의 네트워크 호출 수를 줄이고 reCAPTCHA 신호 수집을 보다 효과적으로 수행하려면 다음과 같이 명시적으로 구성하는 것이 좋습니다.

Swift:

// Initialize Firebase Auth
try await Auth.auth().initializeRecaptchaConfig()

Objective-C:

// Initialize Firebase Auth
[[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
  // Firebase Auth initialization finished
}];

reCAPTCHA 측정항목

reCAPTCHA를 사용 설정한 후에는 프로젝트가 내보내는 reCAPTCHA 측정항목을 모니터링하여 인증 흐름이 보호되는지 확인하세요. reCAPTCHA 사이트 키 프로비저닝이 실패하거나 필요한 서비스 계정이 생성되지 않으면 reCAPTCHA 인증이 실패합니다.

프로젝트가 Cloud Monitoring에 내보내는 다음 측정항목을 검사하여 reCAPTCHA 인증이 작동하는지 확인하세요.

`identitytoolkit.googleapis.com/recaptcha/verdict_count`

reCAPTCHA에서 반환한 다양한 결과를 추적합니다. 토큰이 있으면 결과가 생성됩니다. 다음 결과를 기준으로 필터링할 수 있습니다.

PASSED: 시행이 사용 설정된 경우 지정된 요청이 허용되었음을 나타냅니다.
FAILED_AUDIT: reCAPTCHA 감사 모드가 사용 설정되었을 때 지정된 요청이 거부되었음을 나타냅니다.
FAILED_ENFORCE: reCAPTCHA 시행 모드가 사용 설정되었을 때 지정된 요청이 거부되었음을 나타냅니다.
CLIENT_TYPE_MISSING: reCAPTCHA 시행이 사용 설정된 경우 지정된 요청에 누락된 클라이언트 유형이 있음을 나타냅니다. 이는 일반적으로 reCAPTCHA를 지원하지 않는 오래된 클라이언트 SDK 버전을 사용하여 요청을 보낸 경우에 발생합니다.
KEYS_MISSING: reCAPTCHA 시행이 사용 설정된 경우 유효한 reCAPTCHA 키를 검색하거나 생성할 수 없어 지정된 요청을 확인할 수 없음을 나타냅니다.

점수 범위를 수정하여 통과 및 실패 결과의 비율을 변경하려면 reCAPTCHA Enterprise 사용 설정을 참조하세요.

`identitytoolkit.googleapis.com/recaptcha/token_count`

Identity Platform 백엔드에서 수신한 reCAPTCHA 토큰의 수와 상태를 추적합니다. 다음 상태를 필터링할 수 있습니다.

VALID: 전달된 reCAPTCHA 토큰이 유효함을 나타냅니다.
EXPIRED: 전달된 reCAPTCHA 토큰이 만료되었음을 나타냅니다. 만료된 토큰은 클라이언트 네트워크 문제 또는 악용을 나타내는 것일 수 있습니다.
DUPLICATE: 전달된 reCAPTCHA 토큰이 중복되었음을 나타냅니다. 중복 토큰은 클라이언트 네트워크 문제 또는 악용을 나타내는 것일 수 있습니다.
INVALID: 전달된 reCAPTCHA 토큰이 잘못되었음을 나타냅니다. 잘못된 토큰은 악용을 나타내는 것일 수 있습니다.
MISSING: 지정된 요청에 reCAPTCHA 토큰이 없음을 나타냅니다. 토큰이 누락되면 오래된 클라이언트 앱이 표시될 수 있습니다.
UNCHECKED: CLIENT_TYPE_MISSING 또는 KEYS_MISSING 결과로 인해 reCAPTCHA 토큰이 확인되지 않았음을 나타냅니다.

앱이 사용자에게 정상적으로 출시되면 유효한 토큰이 포함된 트래픽이 표시됩니다. 유효한 토큰 수는 업데이트된 앱을 사용하는 사용자 수에 비례할 가능성이 높습니다.

`identitytoolkit.googleapis.com/recaptcha/risk_scores`

reCAPTCHA 점수 분포를 추적합니다. 이를 통해 구성에 대한 최적의 점수 범위를 정의할 수 있습니다.

이러한 측정항목을 사용하여 시행을 사용 설정할 수 있는지 확인합니다. 시행을 사용 설정하기 전에 다음 사항을 고려해야 합니다.

대부분의 최근 요청에 유효한 토큰이 있고 PASSED ~ FAILED_AUDIT 비율을 가지거나, FAILED_ENFORCE 결과가 사용자의 비즈니스 사례에 허용되는 경우, 시행을 사용 설정하는 것이 좋습니다.
최근 요청의 대부분이 오래된 클라이언트에서 발생한 것 같으면 시행을 사용 설정하기 전에 더 많은 사용자가 앱을 업데이트할 때까지 기다리는 것이 좋습니다. Identity Platform을 reCAPTCHA와 통합하면 reCAPTCHA와 통합되지 않은 이전 앱 버전이 중단됩니다.

이러한 측정항목을 보려면 다음을 수행합니다.

Google Cloud 콘솔에서 측정항목 탐색기 페이지로 이동합니다.

측정항목 탐색기로 이동
측정항목 선택에서 Identity Toolkit 테넌트를 입력합니다. 멀티테넌시를 사용할 경우 tenant_name을 비워 두면 각 테넌트는 물론 상위 프로젝트도 측정항목을 볼 수 있습니다.

적용 사용 설정

앱이 허용되는 사용자 트래픽을 수신하는지 확인한 후 reCAPTCHA 시행을 사용 설정하여 사용자를 보호할 수 있습니다. 이전 버전의 앱을 사용하는 사용자를 포함하여 기존 사용자를 방해하지 않는지 확인하세요.

프로젝트 또는 테넌트에 reCAPTCHA 시행을 사용 설정하려면 Admin SDK를 사용하여 다음을 실행합니다.

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};

reCAPTCHA 사용 중지

reCAPTCHA를 사용 중지하려면 Admin SDK를 사용하여 다음을 실행합니다.

const disableRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'OFF',
  }
};

Cloud Run Functions로 reCAPTCHA 확인 결과 재정의

점수 기준점을 구성하는 것 외에도 커스텀 Cloud Run Functions 차단 함수를 사용하여 지정된 토큰에 대한 reCAPTCHA 확인 결과를 재정의할 수 있습니다. 이는 특정 사용자 로그인의 reCAPTCHA 점수가 낮더라도 사용자를 신뢰할 수 있거나 다른 방법으로 인증하여 로그인을 완료할 수 있는 경우에 유용합니다.

reCAPTCHA로 차단 함수를 구성하는 방법에 대한 자세한 내용은 Cloud Functions 차단으로 Firebase 인증 확장을 참조하세요.

문제 해결

사용자가 로그인, 가입, 비밀번호를 재설정을 할 수 없음

사용자가 이전 버전의 앱을 사용 중일 수 있습니다. 클라이언트 SDK를 사용하는 업데이트된 버전의 앱을 제공하지 않으면 즉시 시행 모드를 사용 중지하세요. 그렇지 않으면 사용자에게 앱을 업데이트하도록 요청하세요.

또는 현재 구성에 따라 사용자가 차단되었을 수 있습니다. 다음을 시도해 보세요.

reCAPTCHA 키 점수를 조정하여 보다 허용적인 구성 고려
사용자에게 다른 기기, 브라우저, 네트워크를 사용하도록 요청
시행 모드를 다시 사용 설정하기 전에 감사 모드로 되돌리고 측정항목을 모니터링하기