감사 모드에서 reCAPTCHA 봇 보호 또는 reCAPTCHA SMS Defense를 사용 설정한 경우 reCAPTCHA 측정항목을 모니터링하면 시행을 사용 설정할 수 있는지 판단하는 데 도움이 됩니다. 시행을 사용 설정하기 전에 다음 사항을 고려해야 합니다.
대부분의 최근 요청에 유효한 토큰이 있고 PASSED ~ FAILED_AUDIT 비율을 가지거나, FAILED_ENFORCE 결과가 사용자의 비즈니스 사례에 허용되는 경우, 시행을 사용 설정하는 것이 좋습니다.
최근 요청의 대부분이 오래된 클라이언트에서 발생한 것 같으면 시행을 사용 설정하기 전에 더 많은 사용자가 앱을 업데이트할 때까지 기다리는 것이 좋습니다. Identity Platform을 reCAPTCHA Enterprise API와 통합하면 reCAPTCHA와 통합되지 않은 이전 앱 버전이 중단됩니다.
통합 기능이 의도한 대로 작동하는지 확인하려면 프로젝트가 Cloud Monitoring에 내보내는 다음 측정항목을 검사하면 됩니다.
[[["이해하기 쉬움","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 details how to monitor reCAPTCHA metrics emitted by Identity Platform after integrating with the reCAPTCHA Enterprise API, including optional SMS toll fraud protection.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eidentitytoolkit.googleapis.com/recaptcha/verdict_count\u003c/code\u003e metric tracks verdicts like \u003ccode\u003ePASSED\u003c/code\u003e, \u003ccode\u003eFAILED_AUDIT\u003c/code\u003e, \u003ccode\u003eFAILED_ENFORCE\u003c/code\u003e, \u003ccode\u003eCLIENT_TYPE_MISSING\u003c/code\u003e, and \u003ccode\u003eKEYS_MISSING\u003c/code\u003e, which indicate the success or failure of reCAPTCHA checks.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eidentitytoolkit.googleapis.com/recaptcha/token_count\u003c/code\u003e metric tracks the status of reCAPTCHA tokens received, including \u003ccode\u003eVALID\u003c/code\u003e, \u003ccode\u003eEXPIRED\u003c/code\u003e, \u003ccode\u003eDUPLICATE\u003c/code\u003e, \u003ccode\u003eINVALID\u003c/code\u003e, \u003ccode\u003eMISSING\u003c/code\u003e, and \u003ccode\u003eUNCHECKED\u003c/code\u003e statuses.\u003c/p\u003e\n"],["\u003cp\u003eMonitoring \u003ccode\u003eidentitytoolkit.googleapis.com/recaptcha/risk_scores\u003c/code\u003e and \u003ccode\u003eidentitytoolkit.googleapis.com/recaptcha/sms_tf_risk_scores\u003c/code\u003e helps define optimal score ranges for bot and SMS toll fraud protection configurations.\u003c/p\u003e\n"],["\u003cp\u003eTo view these metrics, you can access the Metrics Explorer in the Google Cloud console and search for "Identity Toolkit Tenant".\u003c/p\u003e\n"]]],[],null,["# Monitor reCAPTCHA metrics\n=========================\n\nThis document describes the reCAPTCHA metrics that your\nIdentity Platform emits as a result of the Identity Platform integration with the reCAPTCHA Enterprise API and how to\nview them with Cloud Monitoring.\n\nreCAPTCHA metrics\n-----------------\n\nAfter you [set up the\nIdentity Platform integration with the reCAPTCHA Enterprise API](/identity-platform/docs/recaptcha-enterprise), and\noptionally, [enable\nreCAPTCHA SMS defense](/identity-platform/docs/recaptcha-tfp), you\ncan monitor the reCAPTCHA metrics your project emits to ensure\nthat your authentication flows are protected. If reCAPTCHA\nkey provisioning fails or if required service accounts weren't created,\nreCAPTCHA authentication fails open.\n\nIf you've enabled reCAPTCHA bot protection or reCAPTCHA SMS defense in\naudit mode, monitoring the reCAPTCHA metrics will help you\ndetermine if you can enable enforcement. You should consider the following\nbefore enabling enforcement:\n\n- If the majority of recent requests have valid tokens and the ratio of `PASSED` to `FAILED_AUDIT` or `FAILED_ENFORCE` verdicts is acceptable for your business case, consider enabling enforcement.\n- If a majority of the recent requests are likely from outdated clients, consider waiting for more users to update their app before enabling enforcement. Enforcing Identity Platform integration with the reCAPTCHA Enterprise API breaks prior app versions that are not integrated with reCAPTCHA.\n\nTo ensure that the integration features are working as intended, you can examine\nthe following metrics your project emits to Cloud Monitoring.\n\n### `identitytoolkit.googleapis.com/recaptcha/verdict_count`\n\nThis metric tracks the different verdicts returned by reCAPTCHA. A\nverdict is generated if a token is present. You can filter on the following\nverdicts:\n\n- `PASSED`: Indicates that a given request is allowed when enforcement is enabled.\n- `FAILED_AUDIT`: Indicates that a given request is denied when reCAPTCHA audit mode is enabled.\n- `FAILED_ENFORCE`: Indicates that a given request is denied when reCAPTCHA enforcement mode is enabled.\n- `CLIENT_TYPE_MISSING`: Indicates that a given request has a missing client type when reCAPTCHA enforcement is enabled. This error typically occurs if a request was sent using an outdated client SDK version that does not have reCAPTCHA support.\n- `KEYS_MISSING`: Indicates that a given request can't be verified because Identity Platform can't retrieve valid reCAPTCHA keys when reCAPTCHA enforcement is enabled.\n\nTo modify your score ranges to change the ratio of passed-to-failed verdicts,\nsee [Enable reCAPTCHA bot protection](/identity-platform/docs/recaptcha-enterprise#enable).\n\n### `identitytoolkit.googleapis.com/recaptcha/token_count`\n\nThis metric tracks the number and status of reCAPTCHA tokens received\nby the Identity Platform backend. You can filter on the following statuses:\n\n- `VALID`: Indicates that the reCAPTCHA token passed in is valid.\n- `EXPIRED`: Indicates that the reCAPTCHA token passed in has expired. An expired token might indicate client network issues or abuse.\n- `DUPLICATE`: Indicates that the reCAPTCHA token passed in is a duplicate. A duplicate token might indicate client network issues or abuse.\n- `INVALID`: Indicates that the reCAPTCHA token passed in is invalid. An invalid token might indicate abuse.\n- `MISSING`: Indicates that the reCAPTCHA token doesn't exist in the given request. Missing tokens might indicate an outdated client app.\n- `UNCHECKED`: Indicates that the reCAPTCHA token was not checked due to `CLIENT_TYPE_MISSING` or `KEYS_MISSING` verdicts.\n\nIf your app rolled out successfully to users, you will see traffic with valid\ntokens. The number of valid tokens is likely proportional to the number of users\nwho are using your updated app.\n\n### `identitytoolkit.googleapis.com/recaptcha/risk_scores`\n\nThis metric tracks the reCAPTCHA score distribution. This can\nhelp you define the optimal score ranges for your bot protection configuration.\n\n### `identitytoolkit.googleapis.com/recaptcha/sms_tf_risk_scores`\n\nThis metric tracks the reCAPTCHA SMS defense risk score\ndistribution for a particular Identity Platform project. This can help you define the optimal score ranges for your reCAPTCHA SMS defense configuration.\n\nView reCAPTCHA metrics\n----------------------\n\nTo view the reCAPTCHA metrics with Cloud Monitoring, do the\nfollowing:\n\n1. In the Google Cloud console, go to the **Metrics explorer** page.\n\n [Go to Metrics explorer](https://console.cloud.google.com/monitoring/metrics-explorer)\n2. From **Select a metric** , enter **Identity Toolkit Tenant** . If you are\n using multi-tenancy, you can view metrics for each tenant, as well as the\n parent project, by leaving `tenant_name` empty.\n\nWhat's next\n-----------\n\n- Learn how to [troubleshoot common\n issues](/identity-platform/docs/recaptcha-troubleshooting) with the reCAPTCHA integration."]]
