migrate code from googleapis/python-recaptcha-enterprise

recaptcha_enterprise/snippets/annotate_assessment.py

@@ -0,0 +1,43 @@
+# Copyright 2021 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START recaptcha_enterprise_annotate_assessment]
+from google.cloud import recaptchaenterprise_v1
+
+
+def annotate_assessment(project_id: str, assessment_id: str) -> None:
+    """Pre-requisite: Create an assessment before annotating.
+        Annotate an assessment to provide feedback on the correctness of recaptcha prediction.
+    Args:
+        project_id: Google Cloud Project ID
+        assessment_id: Value of the 'name' field returned from the create_assessment() call.
+    """
+
+    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()
+
+    assessment_name = f"projects/{project_id}/assessments/{assessment_id}"
+    # Build the annotation request.
+    # For more info on when/how to annotate, see:
+    # https://cloud.google.com/recaptcha-enterprise/docs/annotate-assessment#when_to_annotate
+    request = recaptchaenterprise_v1.AnnotateAssessmentRequest()
+    request.name = assessment_name
+    request.annotation = request.Annotation.FRAUDULENT
+    request.reasons = [request.Reason.FAILED_TWO_FACTOR]
+
+    # Empty response is sent back.
+    client.annotate_assessment(request)
+    print("Annotated response sent successfully ! ")
+
+
+# [END recaptcha_enterprise_annotate_assessment]

recaptcha_enterprise/snippets/create_assessment.py

@@ -0,0 +1,83 @@
+# Copyright 2021 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START recaptcha_enterprise_create_assessment]
+
+from google.cloud import recaptchaenterprise_v1
+from google.cloud.recaptchaenterprise_v1 import Assessment
+
+
+def create_assessment(
+    project_id: str, recaptcha_site_key: str, token: str, recaptcha_action: str
+) -> Assessment:
+    """Create an assessment to analyze the risk of a UI action.
+    Args:
+        project_id: GCloud Project ID
+        recaptcha_site_key: Site key obtained by registering a domain/app to use recaptcha services.
+        token: The token obtained from the client on passing the recaptchaSiteKey.
+        recaptcha_action: Action name corresponding to the token.
+    """
+
+    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()
+
+    # Set the properties of the event to be tracked.
+    event = recaptchaenterprise_v1.Event()
+    event.site_key = recaptcha_site_key
+    event.token = token
+
+    assessment = recaptchaenterprise_v1.Assessment()
+    assessment.event = event
+
+    project_name = f"projects/{project_id}"
+
+    # Build the assessment request.
+    request = recaptchaenterprise_v1.CreateAssessmentRequest()
+    request.assessment = assessment
+    request.parent = project_name
+
+    response = client.create_assessment(request)
+
+    # Check if the token is valid.
+    if not response.token_properties.valid:
+        print(
+            "The CreateAssessment call failed because the token was "
+            + "invalid for for the following reasons: "
+            + str(response.token_properties.invalid_reason)
+        )
+        return
+
+    # Check if the expected action was executed.
+    if response.token_properties.action != recaptcha_action:
+        print(
+            "The action attribute in your reCAPTCHA tag does"
+            + "not match the action you are expecting to score"
+        )
+        return
+    else:
+        # Get the risk score and the reason(s)
+        # For more information on interpreting the assessment,
+        # see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
+        for reason in response.risk_analysis.reasons:
+            print(reason)
+        print(
+            "The reCAPTCHA score for this token is: "
+            + str(response.risk_analysis.score)
+        )
+        # Get the assessment name (id). Use this to annotate the assessment.
+        assessment_name = client.parse_assessment_path(response.name).get("assessment")
+        print(f"Assessment name: {assessment_name}")
+    return response
+
+
+# [END recaptcha_enterprise_create_assessment]

recaptcha_enterprise/snippets/create_site_key.py

@@ -0,0 +1,66 @@
+# Copyright 2021 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START recaptcha_enterprise_create_site_key]
+from google.cloud import recaptchaenterprise_v1
+
+
+def create_site_key(project_id: str, domain_name: str) -> str:
+    """Create reCAPTCHA Site key which binds a domain name to a unique key.
+    Args:
+    project_id : GCloud Project ID.
+    domain_name: Specify the domain name in which the reCAPTCHA should be activated.
+    """
+    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()
+
+    # Set the type of the reCAPTCHA to be displayed.
+    # For different types, see: https://cloud.google.com/recaptcha-enterprise/docs/keys
+    web_settings = recaptchaenterprise_v1.WebKeySettings()
+    web_settings.allowed_domains.append(domain_name)
+    web_settings.allow_amp_traffic = False
+    web_settings.integration_type = web_settings.IntegrationType.SCORE
+
+    key = recaptchaenterprise_v1.Key()
+    key.display_name = "any descriptive name for the key"
+    key.web_settings = web_settings
+
+    # Create the request.
+    request = recaptchaenterprise_v1.CreateKeyRequest()
+    request.parent = f"projects/{project_id}"
+    request.key = key
+
+    # Get the name of the created reCAPTCHA site key.
+    response = client.create_key(request)
+    recaptcha_site_key = response.name.rsplit("/", maxsplit=1)[1]
+    print("reCAPTCHA Site key created successfully. Site Key: " + recaptcha_site_key)
+    return recaptcha_site_key
+
+
+# [END recaptcha_enterprise_create_site_key]
+
+if __name__ == "__main__":
+    import google.auth
+    import google.auth.exceptions
+
+    # TODO(developer): Replace the below variables before running
+    try:
+        default_project_id = google.auth.default()[1]
+        domain_name = "localhost"
+    except google.auth.exceptions.DefaultCredentialsError:
+        print(
+            "Please use `gcloud auth application-default login` "
+            "or set GOOGLE_APPLICATION_CREDENTIALS to use this script."
+        )
+    else:
+        create_site_key(default_project_id, domain_name)

recaptcha_enterprise/snippets/delete_site_key.py

@@ -0,0 +1,57 @@
+# Copyright 2021 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START recaptcha_enterprise_delete_site_key]
+from google.cloud import recaptchaenterprise_v1
+
+
+def delete_site_key(project_id: str, recaptcha_site_key: str) -> None:
+    """Delete the given reCAPTCHA site key present under the project ID.
+
+    Args:
+    project_id : GCloud Project ID.
+    recaptcha_site_key: Specify the key ID to be deleted.
+    """
+
+    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()
+
+    # Construct the key details.
+    key_name = f"projects/{project_id}/keys/{recaptcha_site_key}"
+
+    # Set the project ID and reCAPTCHA site key.
+    request = recaptchaenterprise_v1.DeleteKeyRequest()
+    request.name = key_name
+
+    client.delete_key(request)
+    print("reCAPTCHA Site key deleted successfully ! ")
+
+
+# [END recaptcha_enterprise_delete_site_key]
+
+
+if __name__ == "__main__":
+    import google.auth
+    import google.auth.exceptions
+
+    # TODO(developer): Replace the below variables before running
+    try:
+        default_project_id = google.auth.default()[1]
+        recaptcha_site_key = "recaptcha_site_key"
+    except google.auth.exceptions.DefaultCredentialsError:
+        print(
+            "Please use `gcloud auth application-default login` "
+            "or set GOOGLE_APPLICATION_CREDENTIALS to use this script."
+        )
+    else:
+        delete_site_key(default_project_id, recaptcha_site_key)

recaptcha_enterprise/snippets/get_metrics.py

@@ -0,0 +1,47 @@
+# Copyright 2021 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START recaptcha_enterprise_get_metrics_site_key]
+from google.cloud import recaptchaenterprise_v1
+
+
+def get_metrics(project_id: str, recaptcha_site_key: str) -> None:
+    """Get metrics specific to a recaptcha site key.
+        E.g: score bucket count for a key or number of
+        times the checkbox key failed/ passed etc.,
+    Args:
+    project_id: Google Cloud Project ID.
+    recaptcha_site_key: Specify the site key to get metrics.
+    """
+
+    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()
+
+    metrics_name = f"projects/{project_id}/keys/{recaptcha_site_key}/metrics"
+    request = recaptchaenterprise_v1.GetMetricsRequest()
+    request.name = metrics_name
+
+    response = client.get_metrics(request)
+
+    # Retrieve the metrics you want from the key.
+    # If the site key is checkbox type: then use response.challenge_metrics
+    # instead of response.score_metrics
+    for day_metric in response.score_metrics:
+        # Each 'day_metric' is in the granularity of one day.
+        score_bucket_count = day_metric.overall_metrics.score_buckets
+        print(score_bucket_count)
+
+    print(f"Retrieved the bucket count for score based key: {recaptcha_site_key}")
+
+
+# [END recaptcha_enterprise_get_metrics_site_key]

recaptcha_enterprise/snippets/get_site_key.py

@@ -0,0 +1,57 @@
+# Copyright 2021 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START recaptcha_enterprise_get_site_key]
+from google.cloud import recaptchaenterprise_v1
+
+
+def get_site_key(project_id: str, recaptcha_site_key: str) -> None:
+    """
+    Get the reCAPTCHA site key present under the project ID.
+
+    Args:
+    project_id: GCloud Project ID.
+    recaptcha_site_key: Specify the site key to get the details.
+    """
+
+    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()
+
+    # Construct the key details.
+    key_name = f"projects/{project_id}/keys/{recaptcha_site_key}"
+
+    request = recaptchaenterprise_v1.GetKeyRequest()
+    request.name = key_name
+
+    key = client.get_key(request)
+    print("Successfully obtained the key !" + key.name)
+
+
+# [END recaptcha_enterprise_get_site_key]
+
+
+if __name__ == "__main__":
+    import google.auth
+    import google.auth.exceptions
+
+    # TODO(developer): Replace the below variables before running
+    try:
+        default_project_id = google.auth.default()[1]
+        recaptcha_site_key = "recaptcha_site_key"
+    except google.auth.exceptions.DefaultCredentialsError:
+        print(
+            "Please use `gcloud auth application-default login` "
+            "or set GOOGLE_APPLICATION_CREDENTIALS to use this script."
+        )
+    else:
+        get_site_key(default_project_id, recaptcha_site_key)