Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Identity Platform을 reCAPTCHA Enterprise API와 통합

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

통합은 사용자를 대신하여 reCAPTCHA Enterprise 평가를 만들어 사용자 요청을 검증합니다. 가격 책정 관련 정보는 reCAPTCHA 가격 책정을 참조하세요.

개요

reCAPTCHA Enterprise API를 사용하여 Identity Platform 통합을 설정하면 reCAPTCHA의 기본 보호 기능인 reCAPTCHA 봇 보호가 사용 설정됩니다. 봇 보호를 사용하면 Identity Platform이 프로젝트에서 점수 기반 reCAPTCHA 키를 자동으로 프로비저닝합니다. 사용자가 다음 작업을 사용하여 앱이나 사이트에 액세스하면 해당 제공업체가 사용 설정된 경우 클라이언트 SDK가 reCAPTCHA를 로드합니다.

제공업체	작업	메서드
`passwordProvider`	이메일 및 비밀번호 로그인	`signInWithPassword`
	이메일 및 비밀번호 가입	`signUpPassword`
	이메일 링크 로그인	`getOobCode`
	비밀번호 재설정	`getOobCode`
`phoneProvider`	전화번호 가입 또는 로그인	`sendVerificationCode`
	MFA 전화번호 등록	`mfaSmsEnrollment`
	MFA 전화번호 로그인	`mfaSmsSignIn`

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

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

시작하기 전에

reCAPTCHA로 보호하려는 인증 흐름 유형에 따라 다음을 설정했는지 확인합니다.

이메일 비밀번호 인증 흐름의 경우 사용자의 이메일 로그인을 구성했는지 확인합니다.
SMS 기반 인증 흐름의 경우 다음 중 하나 이상에 온보딩했는지 확인합니다.
- 사용자의 휴대전화 로그인
- 웹, Android 또는 iOS 앱의 다중 인증

서비스 계정 만들기

reCAPTCHA Enterprise API와 Identity Platform을 통합하려면 reCAPTCHA를 사용할 각 프로젝트에 Identity Platform 서비스 계정이 필요합니다. 이렇게 하면 Identity Platform이 reCAPTCHA 키를 자동으로 관리할 수 있습니다. 이미 서비스 계정을 만든 경우 reCAPTCHA에 대한 액세스 권한을 부여합니다.

아직 서비스 계정을 만들지 않았거나 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. \
    --role=roles/identitytoolkit.serviceAgent

다음을 바꿉니다.

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

제공업체별 reCAPTCHA 봇 보호 동작

reCAPTCHA 봇 보호 동작은 구성하는 ID 공급업체에 따라 다릅니다.

이메일-비밀번호 제공업체

이메일 비밀번호 인증 흐름의 경우 reCAPTCHA 봇 보호는 감사 및 시행의 두 가지 모드를 지원합니다.

감사 모드

이메일 비밀번호 시행을 감사 모드로 설정하면 Identity Platform이 요청을 차단하지 않고 Identity Platform API에 대한 트래픽을 평가하는 데 사용되는 reCAPTCHA 키를 프로젝트에 하나 이상 만듭니다. 감사 모드 중에 내보낸 측정항목을 사용하여 reCAPTCHA 시행을 사용 설정해야 하는지 확인하세요.

시행 모드

이메일 비밀번호 시행을 시행 모드로 설정하면 Identity Platform이 Identity Platform API에 대한 트래픽을 평가하는 데 사용되는 reCAPTCHA 키를 프로젝트에 하나 이상 만듭니다. reCAPTCHA 토큰이 포함되지 않은 API 요청은 거부됩니다. reCAPTCHA를 지원하는 모든 클라이언트를 SDK로 마이그레이션한 후에만 시행을 사용 설정하세요.

전화 서비스 제공업체

phoneEnforcementState를 ENFORCE로, useSmsBotScore를 true로 설정하여 전화 인증 흐름에 봇 보호를 사용 설정하면 Identity Platform은 앱 인증에 reCAPTCHA 봇 보호를 사용합니다. 사용자의 요청이 봇 보호 평가를 통과하면 SMS 인증 코드가 전송됩니다. 사용자의 요청이 봇 보호 평가를 통과하지 못하면 Identity Platform은 요청을 차단하고 인증 코드가 포함된 SMS 메시지를 전송하지 않습니다.

전화 인증 흐름에 봇 보호가 사용 설정된 경우 대체 인증이 필요하지 않으며 앱에 추가 확인 방법을 설정할 필요가 없습니다. 하지만 봇 보호를 사용 중지하기로 결정한 경우 reCAPTCHA v2를 사용할 수 있도록 웹 앱에 reCAPTCHA 인증 도구를 설정하는 것이 좋습니다.

reCAPTCHA Enterprise API와 Identity Platform 통합 설정

reCAPTCHA Enterprise API와 Identity Platform 통합을 설정하려면 다음 작업을 수행합니다.

Admin SDK를 사용하여 reCAPTCHA 시행 상태를 설정하고 봇 보호를 사용 설정합니다.
앱의 플랫폼에 맞게 클라이언트 SDK를 구성합니다.

이메일 비밀번호 인증 흐름의 경우 먼저 감사 모드에서 reCAPTCHA 시행을 사용 설정하고 프로젝트에서 내보내는 reCAPTCHA 측정항목을 모니터링하여 인증 흐름이 보호되는지 확인하는 동안 사용자 트래픽이 중단되지 않도록 하는 것이 좋습니다. 인증 흐름이 보호되는지 확인한 후 봇 보호를 ENFORCE로 설정합니다. 전화 인증 흐름의 경우 phoneEnforcementState를 ENFORCE로, useSmsBotScore를 true로 설정하여 봇 보호를 사용 설정하고 reCAPTCHA 측정항목을 모니터링하여 점수 기준을 미세 조정합니다.

reCAPTCHA 봇 보호 사용 설정

이메일-비밀번호 제공업체

이메일 비밀번호 인증 흐름에 reCAPTCHA 봇 보호를 사용 설정하려면 다음을 수행하세요.

아직 설정하지 않았다면 프로젝트에서 reCAPTCHA Enterprise API를 사용 설정합니다.
프로젝트에 봇 보호를 사용 설정하려면 Admin SDK를 사용합니다. reCAPTCHA 지원은 Node.js Admin SDK 버전 11.7.0 이상에서 제공됩니다.

예를 들면 다음과 같습니다.
```
// Update project config with reCAPTCHA config
const updateConfigRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE_MODE',
    managedRules: [{
      endScore: END_SCORE,
      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);
  });
}
```
다음을 바꿉니다.
- ENFORCE_MODE: reCAPTCHA 이메일 비밀번호 인증 시행에 설정할 모드입니다. 유효한 값은 OFF, AUDIT, ENFORCE입니다. 봇 보호를 사용 설정하려면 이 매개변수를 AUDIT 또는 ENFORCE로 설정해야 합니다. 봇 보호를 처음 사용 설정할 때는 이 매개변수를 AUDIT로 설정하고 인증 흐름이 보호되는지 확인한 후 ENFORCE로 설정하는 것이 좋습니다. 모드 작동 방식에 대한 자세한 내용은 제공업체별 reCAPTCHA 봇 보호 동작을 참조하세요.
- END_SCORE: 요청이 실패하기 전에 가질 수 있는 가장 낮은 봇 보호 평가 점수입니다. 이 점수는 0.0에서 1.0 사이로 설정할 수 있습니다. 예를 들어 기준점을 0.6로 설정하면 reCAPTCHA는 0.5 이하의 요청을 실패로 처리합니다. 따라서 점수를 높게 설정할수록 규칙이 더 엄격해집니다.
Admin SDK를 사용하여 테넌트에 동일한 구성 방법으로 봇 보호를 사용 설정할 수도 있습니다. 테넌트 업데이트에 대한 자세한 내용은 테넌트 업데이트를 참조하세요.
iOS 또는 Android에서 Identity Platform을 사용하는 경우 Firebase Console에서 앱을 등록해야 합니다.
- iOS의 경우 Identity Platform을 사용하는 각 번들 ID를 등록합니다.
- Android의 경우 Identity Platform을 사용하는 각 Android 패키지 이름을 등록합니다.
웹에서 Identity Platform을 사용하는 경우 reCAPTCHA를 사용하는 각 도메인에 승인된 도메인을 추가해야 합니다. 승인된 도메인을 추가하려면 다음을 수행합니다.
1. Google Cloud 콘솔에서 Identity Platform 페이지로 이동합니다.
  
  Identity Platform으로 이동
2. 설정 > 보안으로 이동합니다.
3. 도메인 추가를 클릭합니다.
4. 도메인 이름을 입력하고 추가를 클릭하여 도메인을 저장합니다.
reCAPTCHA 키 프로비저닝을 완료하는 데 몇 분 정도 걸릴 수 있습니다.
시행을 감사 모드로 설정한 경우 봇 보호를 위한 reCAPTCHA 측정항목을 모니터링하여 흐름이 보호되는지 확인하는 것이 좋습니다.

전화 서비스 제공업체

SMS 기반 인증 흐름에 reCAPTCHA 봇 보호를 사용 설정하려면 다음을 수행합니다.

아직 설정하지 않았다면 프로젝트에서 reCAPTCHA Enterprise API를 사용 설정합니다.
프로젝트에 봇 보호를 사용 설정하려면 Admin SDK를 사용합니다. reCAPTCHA 지원은 Node.js Admin SDK 버전 12.7.0 이상에서 제공됩니다.

예를 들면 다음과 같습니다.
```
// Update project config with reCAPTCHA config
const updateProjectConfigRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'ENFORCE',
    managedRules: [{
      endScore: END_SCORE,
      action: 'BLOCK'
    }],
    useSmsBotScore: true,
  }
};
let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);
```
END_SCORE을 요청이 실패하기 전에 가질 수 있는 가장 낮은 봇 보호 평가 점수로 바꿉니다. 이 점수는 0.0에서 1.0 사이로 설정할 수 있습니다. 예를 들어 기준점을 0.6로 설정하면 reCAPTCHA는 0.5 이하의 요청을 실패로 처리합니다. 따라서 점수를 높게 설정할수록 규칙이 더 엄격해집니다.

phoneEnforcementState를 ENFORCE로, useSmsBotScore를 true로 설정하면 SMS 기반 인증 흐름에 봇 보호 시행이 사용 설정됩니다. 전화 제공업체 시행 방식에 대한 자세한 내용은 제공업체별 reCAPTCHA 봇 보호 동작을 참조하세요.

Admin SDK를 사용하여 테넌트에 동일한 구성 방법으로 봇 보호를 사용 설정할 수도 있습니다. 테넌트 업데이트에 대한 자세한 내용은 테넌트 업데이트를 참조하세요.

참고: Identity Platform은 모바일 플랫폼에서 여러 테넌트와 함께 전화 인증 및 SMS 다중 인증(MFA)을 사용하는 것을 지원하지 않습니다.
iOS 또는 Android에서 Identity Platform을 사용하는 경우 Firebase Console에서 앱을 등록해야 합니다.
- iOS의 경우 Identity Platform을 사용하는 각 번들 ID를 등록합니다.
- Android의 경우 Identity Platform을 사용하는 각 Android 패키지 이름을 등록합니다.
웹에서 Identity Platform을 사용하는 경우 reCAPTCHA를 사용하는 각 도메인에 승인된 도메인을 추가해야 합니다. 승인된 도메인을 추가하려면 다음을 수행합니다.
1. Google Cloud 콘솔에서 Identity Platform 페이지로 이동합니다.
  
  Identity Platform으로 이동
2. 설정 > 보안으로 이동합니다.
3. 도메인 추가를 클릭합니다.
4. 도메인 이름을 입력하고 추가를 클릭하여 도메인을 저장합니다.
reCAPTCHA 키 프로비저닝을 완료하는 데 몇 분 정도 걸릴 수 있습니다.
봇 보호를 위한 reCAPTCHA 측정항목을 모니터링하여 흐름이 보호되는지 확인합니다.

클라이언트 SDK 구성

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

웹

최신 버전의 웹 SDK로 업데이트합니다.
- 웹 앱의 이메일 및 비밀번호 인증에 대한 reCAPTCHA 지원은 JavaScript SDK 버전 9.20.0 이상에서 제공됩니다.
- 웹 앱의 전화 인증에 대한 reCAPTCHA 지원은 JavaScript SDK 버전 11 이상에서 제공됩니다.
웹 SDK를 앱에 통합하면 SDK가 reCAPTCHA 구성을 자동으로 가져오고 구성한 제공업체에 대한 보호를 사용 설정합니다.

필요한 경우 다음과 같이 reCAPTCHA 신호를 강제로 가져올 수 있습니다.

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

// Initialize Firebase Authentication
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로 업데이트합니다. Android 앱의 이메일 및 비밀번호 인증과 전화 인증에 대한 reCAPTCHA 지원은 Android SDK 버전 23.1.0 이상에서 사용할 수 있습니다.

또한 reCAPTCHA 지원에는 API 수준 23(Marshmallow) 이상 및 Android 6 이상이 필요합니다.

Android SDK를 앱과 통합하면 SDK가 reCAPTCHA 구성을 자동으로 가져오고 구성한 제공업체에 대한 보호를 사용 설정합니다.
앱 수준 build.gradle 파일의 종속 항목 섹션에 다음 빌드 규칙을 추가하세요.
```
implementation 'com.google.android.recaptcha:recaptcha:18.5.1'
```
reCAPTCHA SDK 버전 18.5.1 이상을 사용해야 합니다.

필요한 경우 다음과 같이 reCAPTCHA 신호를 강제로 가져올 수 있습니다.

Kotlin:

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

필요한 경우 다음과 같이 reCAPTCHA 신호를 강제로 가져올 수 있습니다.

Swift:

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

Objective-C:

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

봇 보호를 위한 reCAPTCHA 측정항목 모니터링

프로젝트가 내보내는 reCAPTCHA 측정항목을 모니터링하여 인증 흐름이 보호되는지 확인하세요. 이메일-비밀번호 인증 흐름의 경우 시행을 시행 모드로 설정하기 전에 감사 모드에서 측정항목을 모니터링하는 것이 좋습니다. 예를 들어 이러한 측정항목은 reCAPTCHA Enterprise API와 Identity Platform 통합을 올바르게 설정했는지 확인하는 데 도움이 될 수 있습니다. 또한 사용자 트래픽의 점수 기준점을 미세 조정하는 데도 도움이 될 수 있습니다. reCAPTCHA 키 프로비저닝이 실패하거나 필요한 서비스 계정이 생성되지 않은 경우에도 reCAPTCHA 인증 시도는 정상적으로 성공합니다.

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

identitytoolkit.googleapis.com/recaptcha/verdict_count: reCAPTCHA에서 반환한 다양한 결과를 추적합니다.
identitytoolkit.googleapis.com/recaptcha/token_count: Identity Platform 백엔드에서 수신한 reCAPTCHA 토큰의 수와 상태를 추적합니다.
identitytoolkit.googleapis.com/recaptcha/risk_scores: 봇 보호 점수 분포를 추적합니다.

자세한 내용은 reCAPTCHA 측정항목 모니터링을 참조하세요.

이메일 비밀번호 흐름에 reCAPTCHA 봇 보호 시행

처음에 AUDIT 모드로 구성한 이메일 비밀번호 인증 흐름의 경우 앱이 허용되는 사용자 트래픽을 수신하는지 확인한 후 emailPasswordEnforcementState를 ENFORCE로 전환하여 reCAPTCHA 평가에 실패한 요청을 차단할 수 있습니다. 이전 버전의 앱을 사용하는 사용자를 포함하여 기존 사용자를 방해하지 않는지 확인하세요.

프로젝트 또는 테넌트에서 이메일-비밀번호 인증 흐름에 reCAPTCHA 시행을 사용 설정하려면 Admin SDK를 사용하여 다음 코드를 실행합니다.

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState: 'ENFORCE',
  }
};

reCAPTCHA 봇 보호 사용 중지

이메일-비밀번호 제공업체

이메일 비밀번호 인증 흐름에 대한 봇 보호를 사용 중지하려면 Admin SDK를 사용하여 다음 명령어를 실행합니다.

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

전화 서비스 제공업체

SMS 기반 인증 흐름에서 봇 보호를 포함한 모든 전화 reCAPTCHA 보호를 사용 중지하려면 Admin SDK를 사용하여 다음 명령어를 실행합니다.

const disableRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'OFF',
    useSmsBotScore: false,
    useSmsTollFraudProtection: false
  }
};

reCAPTCHA SMS 방어도 사용 중이고 봇 보호를 사용 중지하는 동안 사용 설정된 상태로 유지하려면 useSmsBotScore를 false로 설정하고 phoneEnforcementState를 ENFORCE로 설정합니다.

const disableBotScoreOnlyRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'ENFORCE',
    useSmsBotScore: false,
    useSmsTollFraudProtection: true
  }
};

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

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

다음 예시에서는 차단 함수를 사용하여 reCAPTCHA 결과를 재정의하는 방법을 보여줍니다.

Node.js

  const functions = require("firebase-functions/v1");
  exports.beforesmsv1 = functions.auth.user().beforeSms((context) => {
    if (
      context.smsType === "SIGN_IN_OR_SIGN_UP" &&
      context.additionalUserInfo.phoneNumber.includes('+91')
    ) {
      return {
        recaptchaActionOverride: "ALLOW",
      };
    }

    // Allow users to sign in with recaptcha score greater than 0.5
    if (event.additionalUserInfo.recaptchaScore > 0.5) {
      return {
        recaptchaActionOverride: 'ALLOW',
      };
    }

    // Block all others.
    return  {
      recaptchaActionOverride: 'BLOCK',
    }
  });

다음 단계

SMS 기반 인증 흐름에 reCAPTCHA SMS 방어를 사용 설정합니다.
자체 reCAPTCHA 키를 사용하는 방법을 알아보세요.
reCAPTCHA 측정항목 모니터링에 대해 자세히 알아보세요.
reCAPTCHA에 대해 자세히 알아보세요.