Identity Platform과 reCAPTCHA Enterprise API 통합 문제 해결
이 문서에서는 reCAPTCHA 봇 보호 및 reCAPTCHA SMS 방어 기능을 비롯하여 Identity Platform을 reCAPTCHA Enterprise API와 통합할 때 발생할 수 있는 잠재적 문제를 해결하는 방법을 안내합니다.
통합 온보딩 문제 해결
Identity Platform과 reCAPTCHA Enterprise API 통합을 온보딩할 때 실수로 인해 사용자에게 문제가 발생할 수 있습니다. 일반적인 이유는 다음과 같습니다.
Identity Platform을 reCAPTCHA Enterprise API와 통합하는 단계에서 누락된 단계가 있을 수 있습니다. 예를 들어 서비스 계정을 설정하지 않거나 프로젝트에서 reCAPTCHA Enterprise API를 사용 설정하지 않는 경우입니다. 모든 통합 요구사항을 완료했는지 확인합니다. 설정 안내는 Identity Platform을 reCAPTCHA Enterprise API와 통합을 참고하세요.
reCAPTCHA와 함께 사용하기 위해 자체 키를 가져오고 있는 경우 업로드한 해당 reCAPTCHA 키가 유효하지 않거나 작동하지 않을 수 있습니다. 키가 작동하고 Identity Platform에서 액세스할 수 있는지 확인합니다.
사용자가 이전 버전의 앱을 사용 중일 수 있습니다. 클라이언트 SDK를 사용하는 업데이트된 버전의 앱을 제공하고 사용자에게 앱을 업데이트하도록 요청하세요. 앱의 클라이언트 SDK를 설정하려면 클라이언트 SDK 구성을 참고하세요.
사용자가 reCAPTCHA Enterprise API 지원 흐름을 통해 인증할 수 없음
reCAPTCHA 봇 보호 또는 reCAPTCHA SMS 방어와 같은 reCAPTCHA Enterprise API 지원 흐름에 문제가 발생하면 다음 섹션에서 기능별 안내를 참고하세요.
reCAPTCHA 봇 보호 문제 해결
다음 주제에서는 봇 보호를 사용할 때 발생할 수 있는 문제와 해결 방법을 설명합니다.
이메일-비밀번호 또는 전화 제공업체에 봇 보호를 사용하면 사용자가 인증할 수 없음
Identity Platform과 reCAPTCHA Enterprise API의 통합이 올바르게 설정되었다고 판단되면 현재 구성에 따라 사용자가 이메일-비밀번호 또는 전화 제공업체를 통해 인증 작업을 수행하지 못하도록 차단될 수 있습니다. 예를 들어 사용자는 다음 작업을 수행하지 못할 수 있습니다.
이메일 주소를 통해 로그인, 가입 또는 비밀번호 재설정
전화번호를 통해 로그인할 SMS 코드를 요청합니다.
SMS 기반 다단계 인증을 등록하거나 이 인증으로 로그인합니다.
이러한 인증 문제를 해결하려면 다음을 시도해 보세요.
ERROR_CAPTCHA_CHECK_FAILED로 사용자 요청이 실패하는 경우 managedRules에 설정한 임곗값을 조정하여 더 관대한 구성을 고려해 보세요. 설정한 기준점 미만의 점수를 받은 요청은 봇으로 간주됩니다. 예를 들어 임곗값을 0.6로 설정하면 reCAPTCHA는 0.5 이하의 요청을 실패로 간주합니다.
따라서 점수를 높게 설정할수록 규칙이 더 엄격해집니다.
사용자에게 다른 기기, 브라우저, 네트워크를 사용하도록 요청
시행 모드를 다시 사용 설정하기 전에 감사 모드로 되돌리고 측정항목을 모니터링하기
reCAPTCHA SMS Defense 문제 해결
다음 주제에서는 reCAPTCHA SMS 방어를 사용할 때 발생할 수 있는 문제와 해결 방법을 설명합니다.
전화 제공업체에 reCAPTCHA SMS 방어를 사용할 때 사용자가 인증할 수 없음
Identity Platform과 reCAPTCHA Enterprise API의 통합이 올바르게 설정되었다고 판단되면 현재 구성에 따라 사용자가 전화 제공업체를 통해 SMS 기반 인증 작업을 실행하지 못하도록 차단될 수 있습니다. 예를 들어 사용자가 전화번호로 로그인하거나 다단계 인증에 등록하거나 다단계 인증으로 로그인하기 위해 SMS 코드를 요청할 수 없습니다. 이는 설정된 reCAPTCHA SMS 방어 점수가 너무 엄격한 경우 발생할 수 있습니다.
이 문제를 해결하려면 tollFraudManagedRules에 설정한 임곗값을 조정하여 보다 허용적인 구성을 고려하세요. 설정한 기준을 초과하는 점수는 SMS 요금 사기로 간주됩니다. 예를 들어 기준을 0.3로 설정하면 reCAPTCHA는 0.4 이상의 요청을 실패로 처리합니다.
따라서 점수를 낮게 설정할수록 규칙이 더 엄격해집니다.
이 문제가 발생하는 경우 시행 모드를 감사로 설정하여 프로젝트에서 내보내는 reCAPTCHA 측정항목을 테스트하고 모니터링하는 것이 좋습니다. 이렇게 하면 시행을 다시 사용 설정하기 전에 앱이 허용되는 사용자 트래픽을 수신하는지 확인할 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eThis document offers guidance on troubleshooting issues with the Identity Platform integration with the reCAPTCHA Enterprise API, which includes bot protection and SMS toll fraud protection.\u003c/p\u003e\n"],["\u003cp\u003eCommon issues during onboarding can stem from missed setup steps, like neglecting to set up the service account or using an invalid reCAPTCHA key, or if users are using outdated app versions.\u003c/p\u003e\n"],["\u003cp\u003eUsers might face authentication failures due to strict configurations; adjusting the \u003ccode\u003emanagedRules\u003c/code\u003e thresholds in bot protection or the \u003ccode\u003etollFraudManagedRules\u003c/code\u003e thresholds in SMS toll fraud protection can resolve these issues.\u003c/p\u003e\n"],["\u003cp\u003eWhen encountering authentication issues, you can ask users to try a different device, browser, or network, or revert to audit mode to monitor metrics before re-enabling enforcement mode.\u003c/p\u003e\n"],["\u003cp\u003eIf SMS toll fraud protection is blocking authentication, consider lowering the score threshold to be more permissive, and use audit mode to test and monitor metrics.\u003c/p\u003e\n"]]],[],null,["# Troubleshooting the Identity Platform integration with the reCAPTCHA Enterprise API\n===================================================================================\n\nThis document provides guidance for troubleshooting potential issues that might\narise when using the Identity Platform integration with the reCAPTCHA Enterprise API, including the\nreCAPTCHA bot protection and reCAPTCHA SMS defense features.\n\nIntegration onboarding troubleshooting\n--------------------------------------\n\nYour users might be experiencing issues due to mistakes when onboarding\nwith the Identity Platform integration with the reCAPTCHA Enterprise API. Some common reasons might include the\nfollowing:\n\n- You might have missed a step in the Identity Platform integration with the reCAPTCHA Enterprise API set up. For example, neglecting to set up the service account or enabling the reCAPTCHA Enterprise API on the project. Ensure you've completed all the integration requirements. For set up instructions, see [Integrate\n Identity Platform with the reCAPTCHA Enterprise\n API](/identity-platform/docs/recaptcha-enterprise).\n- If you are [bringing your own key](/identity-platform/docs/recaptcha-byok) to use with reCAPTCHA, the corresponding reCAPTCHA key you uploaded might not be valid or might have stopped working. Verify that the key is working and accessible by Identity Platform.\n- Users might be using an outdated version of your app. Make sure you provide an updated version of your app that uses the client SDK, and ask your users to update their app. To set up the client SDK for your app, see [Configure\n the\n client SDK](/identity-platform/docs/recaptcha-enterprise#configure-sdk).\n\nUsers can't authenticate through reCAPTCHA Enterprise API supported flows\n-------------------------------------------------------------------------\n\nIf you are experiencing issues with reCAPTCHA Enterprise API supported\nflows, such as reCAPTCHA bot protection or reCAPTCHA SMS defense, see the\nfollowing sections for feature specific guidance.\n\n### reCAPTCHA bot protection troubleshooting\n\nThe following topics describe possible issues that you might face when using\nbot protection and how you might solve them.\n\n#### Users can't authenticate when using bot protection for the email-password or phone providers\n\nIf you have determined that the Identity Platform integration with the reCAPTCHA Enterprise API was set up correctly,\nusers might be blocked from performing authentication actions through the\nemail-password or phone providers based on your current configuration. For\nexample, users might be unable to perform the following actions:\n\n- Sign-in, sign-up, or reset a password through an email address.\n- Request an SMS code to sign in through a phone number.\n- Enroll in or sign in with SMS-based multi-factor authentication.\n\nTo resolve these authentication issues, try the following:\n\n- If user requests are failing with `ERROR_CAPTCHA_CHECK_FAILED`, consider a more permissive configuration by adjusting the thresholds you've set for `managedRules`. Any requests that score below the threshold you set will be considered a bot. For example, if you set a threshold of `0.6`, reCAPTCHA will fail any request with a `0.5` or lower. Therefore, the higher you set the score, the stricter the rules will be.\n- Ask the user to try a different device, browser, or network.\n- Revert to audit mode and monitor metrics before re-enabling enforcement mode.\n\n### reCAPTCHA SMS defense troubleshooting\n\nThe following topics describe possible issues you might face when using\nreCAPTCHA SMS defense and how you might solve them.\n\n#### Users can't authenticate when using reCAPTCHA SMS defense for the phone provider\n\nIf you have determined that the Identity Platform integration with the reCAPTCHA Enterprise API was set up correctly,\nusers might be blocked from performing SMS-based authentication actions through\nthe phone provider based on your current configuration. For example, users might\nbe unable to request an SMS code to sign in with a phone number or enroll in or\nsign in with multi-factor authentication. This can happen if the\nreCAPTCHA SMS defense score you set is too strict.\n\nTo resolve this, consider a more permissive configuration by adjusting the\nthreshold you've set for `tollFraudManagedRules`. Any score above the threshold\nyou set will be considered SMS toll fraud. For example, if you set a threshold\nof `0.3`, reCAPTCHA will fail any request with a `0.4` or higher.\nTherefore, the lower you set the score, the stricter the rules will be.\n\nIf this is an issue, we recommend setting your enforcement mode to audit to test\nand monitor the reCAPTCHA metrics emitted by your project. This\nwill help you ensure that your app is receiving acceptable user traffic before\nenabling enforcement again.\n\nWhat's next\n-----------\n\n- Learn more about [monitoring reCAPTCHA\n metrics](/identity-platform/docs/recaptcha-metrics)."]]
