docs(samples): added recaptcha code samples and tests

.kokoro/docker/samples/Dockerfile

@@ -0,0 +1,36 @@
+# Copyright 2021 Google LLC
+#
+# 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.
+
+# Use the python-docs-samples iamge as a base:
+# https://github.com/GoogleCloudPlatform/python-docs-samples/blob/master/.kokoro/docker/Dockerfile
+FROM gcr.io/cloud-devrel-kokoro-resources/python-samples-testing-docker
+
+# Install Chrome.
+RUN curl https://dl-ssl.google.com/linux/linux_signing_key.pub -o /tmp/google.pub \
+    && cat /tmp/google.pub | apt-key add -; rm /tmp/google.pub \
+    && echo 'deb http://dl.google.com/linux/chrome/deb/ stable main' > /etc/apt/sources.list.d/google.list \
+    && mkdir -p /usr/share/desktop-directories \
+    && apt-get -y update && apt-get install -y google-chrome-stable
+
+# Disable the SUID sandbox so that Chrome can launch without being in a privileged container.
+RUN dpkg-divert --add --rename --divert /opt/google/chrome/google-chrome.real /opt/google/chrome/google-chrome \
+    && echo "#!/bin/bash\nexec /opt/google/chrome/google-chrome.real --no-sandbox --disable-setuid-sandbox \"\$@\"" > /opt/google/chrome/google-chrome \
+    && chmod 755 /opt/google/chrome/google-chrome
+
+# Install Chrome Driver.
+RUN mkdir -p /opt/selenium \
+    && curl http://chromedriver.storage.googleapis.com/`curl -sS chromedriver.storage.googleapis.com/LATEST_RELEASE`/chromedriver_linux64.zip -o /opt/selenium/chromedriver_linux64.zip \
+    && cd /opt/selenium; unzip /opt/selenium/chromedriver_linux64.zip; rm -rf chromedriver_linux64.zip; ln -fs /opt/selenium/chromedriver /usr/local/bin/chromedriver;
+
+CMD ["python3.6"]

.kokoro/samples/lint/common.cfg

@@ -18,10 +18,15 @@ env_vars: {
     value: "github/python-recaptcha-enterprise/.kokoro/test-samples.sh"
 }
 
-# Configure the docker image for kokoro-trampoline.
 env_vars: {
     key: "TRAMPOLINE_IMAGE"
-    value: "gcr.io/cloud-devrel-kokoro-resources/python-samples-testing-docker"
+    value: "gcr.io/cloud-devrel-kokoro-resources/python-recaptcha-enterprise-samples-docker"
+}
+
+# Configure the docker image for kokoro-trampoline.
+env_vars: {
+    key: "TRAMPOLINE_DOCKERFILE"
+    value: ".kokoro/docker/samples/Dockerfile"
 }
 
 # Download secrets for samples

.kokoro/samples/python3.10/common.cfg

@@ -24,10 +24,15 @@ env_vars: {
     value: "github/python-recaptcha-enterprise/.kokoro/test-samples.sh"
 }
 
-# Configure the docker image for kokoro-trampoline.
 env_vars: {
     key: "TRAMPOLINE_IMAGE"
-    value: "gcr.io/cloud-devrel-kokoro-resources/python-samples-testing-docker"
+    value: "gcr.io/cloud-devrel-kokoro-resources/python-recaptcha-enterprise-samples-docker"
+}
+
+# Configure the docker image for kokoro-trampoline.
+env_vars: {
+    key: "TRAMPOLINE_DOCKERFILE"
+    value: ".kokoro/docker/samples/Dockerfile"
 }
 
 # Download secrets for samples

.kokoro/samples/python3.10/periodic-head.cfg

@@ -9,3 +9,9 @@ env_vars: {
     key: "TRAMPOLINE_BUILD_FILE"
     value: "github/python-recaptcha-enterprise/.kokoro/test-samples-against-head.sh"
 }
+
+# Upload the docker image after successful builds.
+env_vars: {
+    key: "TRAMPOLINE_IMAGE_UPLOAD"
+    value: "true"
+}

.kokoro/samples/python3.10/periodic.cfg

@@ -4,3 +4,9 @@ env_vars: {
     key: "INSTALL_LIBRARY_FROM_SOURCE"
     value: "False"
 }
+
+# Upload the docker image after successful builds.
+env_vars: {
+    key: "TRAMPOLINE_IMAGE_UPLOAD"
+    value: "true"
+}

.kokoro/samples/python3.6/common.cfg

@@ -24,10 +24,15 @@ env_vars: {
     value: "github/python-recaptcha-enterprise/.kokoro/test-samples.sh"
 }
 
-# Configure the docker image for kokoro-trampoline.
 env_vars: {
     key: "TRAMPOLINE_IMAGE"
-    value: "gcr.io/cloud-devrel-kokoro-resources/python-samples-testing-docker"
+    value: "gcr.io/cloud-devrel-kokoro-resources/python-recaptcha-enterprise-samples-docker"
+}
+
+# Configure the docker image for kokoro-trampoline.
+env_vars: {
+    key: "TRAMPOLINE_DOCKERFILE"
+    value: ".kokoro/docker/samples/Dockerfile"
 }
 
 # Download secrets for samples

.kokoro/samples/python3.6/periodic-head.cfg

@@ -9,3 +9,9 @@ env_vars: {
     key: "TRAMPOLINE_BUILD_FILE"
     value: "github/python-recaptcha-enterprise/.kokoro/test-samples-against-head.sh"
 }
+
+# Upload the docker image after successful builds.
+env_vars: {
+    key: "TRAMPOLINE_IMAGE_UPLOAD"
+    value: "true"
+}

.kokoro/samples/python3.6/periodic.cfg

@@ -4,3 +4,9 @@ env_vars: {
     key: "INSTALL_LIBRARY_FROM_SOURCE"
     value: "False"
 }
+
+# Upload the docker image after successful builds.
+env_vars: {
+    key: "TRAMPOLINE_IMAGE_UPLOAD"
+    value: "true"
+}

.kokoro/samples/python3.7/common.cfg

@@ -24,10 +24,15 @@ env_vars: {
     value: "github/python-recaptcha-enterprise/.kokoro/test-samples.sh"
 }
 
-# Configure the docker image for kokoro-trampoline.
 env_vars: {
     key: "TRAMPOLINE_IMAGE"
-    value: "gcr.io/cloud-devrel-kokoro-resources/python-samples-testing-docker"
+    value: "gcr.io/cloud-devrel-kokoro-resources/python-recaptcha-enterprise-samples-docker"
+}
+
+# Configure the docker image for kokoro-trampoline.
+env_vars: {
+    key: "TRAMPOLINE_DOCKERFILE"
+    value: ".kokoro/docker/samples/Dockerfile"
 }
 
 # Download secrets for samples

.kokoro/samples/python3.7/periodic.cfg

@@ -4,3 +4,9 @@ env_vars: {
     key: "INSTALL_LIBRARY_FROM_SOURCE"
     value: "False"
 }
+
+# Upload the docker image after successful builds.
+env_vars: {
+    key: "TRAMPOLINE_IMAGE_UPLOAD"
+    value: "true"
+}

.kokoro/samples/python3.8/common.cfg

@@ -24,10 +24,15 @@ env_vars: {
     value: "github/python-recaptcha-enterprise/.kokoro/test-samples.sh"
 }
 
-# Configure the docker image for kokoro-trampoline.
 env_vars: {
     key: "TRAMPOLINE_IMAGE"
-    value: "gcr.io/cloud-devrel-kokoro-resources/python-samples-testing-docker"
+    value: "gcr.io/cloud-devrel-kokoro-resources/python-recaptcha-enterprise-samples-docker"
+}
+
+# Configure the docker image for kokoro-trampoline.
+env_vars: {
+    key: "TRAMPOLINE_DOCKERFILE"
+    value: ".kokoro/docker/samples/Dockerfile"
 }
 
 # Download secrets for samples

.kokoro/samples/python3.8/periodic-head.cfg

@@ -9,3 +9,9 @@ env_vars: {
     key: "TRAMPOLINE_BUILD_FILE"
     value: "github/python-recaptcha-enterprise/.kokoro/test-samples-against-head.sh"
 }
+
+# Upload the docker image after successful builds.
+env_vars: {
+    key: "TRAMPOLINE_IMAGE_UPLOAD"
+    value: "true"
+}

.kokoro/samples/python3.8/periodic.cfg

@@ -4,3 +4,9 @@ env_vars: {
     key: "INSTALL_LIBRARY_FROM_SOURCE"
     value: "False"
 }
+
+# Upload the docker image after successful builds.
+env_vars: {
+    key: "TRAMPOLINE_IMAGE_UPLOAD"
+    value: "true"
+}

.kokoro/samples/python3.9/common.cfg

@@ -24,10 +24,15 @@ env_vars: {
     value: "github/python-recaptcha-enterprise/.kokoro/test-samples.sh"
 }
 
-# Configure the docker image for kokoro-trampoline.
 env_vars: {
     key: "TRAMPOLINE_IMAGE"
-    value: "gcr.io/cloud-devrel-kokoro-resources/python-samples-testing-docker"
+    value: "gcr.io/cloud-devrel-kokoro-resources/python-recaptcha-enterprise-samples-docker"
+}
+
+# Configure the docker image for kokoro-trampoline.
+env_vars: {
+    key: "TRAMPOLINE_DOCKERFILE"
+    value: ".kokoro/docker/samples/Dockerfile"
 }
 
 # Download secrets for samples

.kokoro/samples/python3.9/periodic-head.cfg

@@ -9,3 +9,9 @@ env_vars: {
     key: "TRAMPOLINE_BUILD_FILE"
     value: "github/python-recaptcha-enterprise/.kokoro/test-samples-against-head.sh"
 }
+
+# Upload the docker image after successful builds.
+env_vars: {
+    key: "TRAMPOLINE_IMAGE_UPLOAD"
+    value: "true"
+}

.kokoro/samples/python3.9/periodic.cfg

@@ -4,3 +4,9 @@ env_vars: {
     key: "INSTALL_LIBRARY_FROM_SOURCE"
     value: "False"
 }
+
+# Upload the docker image after successful builds.
+env_vars: {
+    key: "TRAMPOLINE_IMAGE_UPLOAD"
+    value: "true"
+}

owlbot.py

@@ -39,7 +39,7 @@
 # ----------------------------------------------------------------------------
 # Add templated files
 # ----------------------------------------------------------------------------
-templated_files = common.py_library(cov_level=98, microgenerator=True)
+templated_files = common.py_library(cov_level=98, microgenerator=True, custom_samples_dockerfile=True)
 
 s.move(
     templated_files, excludes=[".coveragerc"]

samples/snippets/create_assessment.py

@@ -0,0 +1,80 @@
+# 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
+
+
+def create_assessment(
+    project_id: str, recaptcha_site_key: str, token: str, recaptcha_action: str
+) -> None:
+    """ 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.
+    """
+
+    # TODO(developer): Replace these variables before running the sample.
+    # Specify a name for this assessment.
+    assessment_name = "assessment_name"
+
+    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
+    assessment.name = assessment_name
+
+    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)
+        )
+    else:
+        # Check if the expected action was executed.
+        if response.token_properties.action == recaptcha_action:
+            # 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)
+            )
+        else:
+            print(
+                "The action attribute in your reCAPTCHA tag does"
+                + "not match the action you are expecting to score"
+            )
+
+
+# [END recaptcha_enterprise_create_assessment]

samples/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)