Recaptcha Helloworld


This is a trivial reCaptcha tutorial covering a single page “app” that validates and displays the score associated with a user for:

  • Scoring
  • Checkbox

Basically, you will setup recaptcha and run a simple golang https webserver that will perform basic recaptcha functions.

The steps here are

  1. enable recaptcha api
  2. create service account key
  3. assign service account IAM permissions for roles/recaptchaenterprise.agent
  4. create recaptcha site keys
  5. add keys to page
  6. start webserver
  7. check if you’re a robot

This repo is not supported by Google

you can find the sourcecode here: Recaptcha Helloworld

Steps 1->3

export PROJECT_ID=`gcloud config get-value core/project`
export PROJECT_NUMBER=`gcloud projects describe $PROJECT_ID --format='value(projectNumber)'`

gcloud services enable recaptchaenterprise.googleapis.com

gcloud iam service-accounts create recaptcha-client-account --display-name "recaptcha site Service Account"

gcloud iam service-accounts keys create recaptcha-svc.json --iam-account=recaptcha-client-account@$PROJECT_ID.iam.gserviceaccount.com

gcloud projects add-iam-policy-binding $PROJECT_ID \
       --member serviceAccount:recaptcha-client-account@$PROJECT_ID.iam.gserviceaccount.com   \
       --role roles/recaptchaenterprise.agent

note, i’m downloading a service account key here just as a demo…normally, you should try to not distribute keys if you can help it. For more info, see Service Account Best Practices

Step 4

Now create keys for “scoring” and “checkbox” as described here

gcloud alpha recaptcha keys create \
  --web \
  --display-name="Score Key"  \
  --integration-type=SCORE \

gcloud alpha recaptcha keys create \
  --web \
  --display-name="Checkbox Key"  \
  --integration-type=CHECKBOX \


Note, the host local.esodemoapp2.com resolves to and is used to communicate to your local webserver which we will run later

Step 5

Edit static/score.html and place the value for the scoring key into the following sections

          <script src="https://www.google.com/recaptcha/enterprise.js?render=6Lefk7QaAAAAAJAtX1S7W_pXQz1tS2LLFAYXB9q-"></script>

            function recaptcha_call() {
              grecaptcha.enterprise.execute('6Lefk7QaAAAAAJAtX1S7W_pXQz1tS2LLFAYXB9q-', {action: 'homepage'}).then(function(token) {

Edit static/checkbox.html and place the value for the check key into the following sections

          <div class="g-recaptcha" data-callback="recaptcha_callback" data-sitekey="6LenwLMaAAAAAJiGCftfhT2Iv-g5F_LSfKkj6B69"></div>

Step 6

Edit httpserver/server.go and apply the appropriate const values (eg, the keys, the projectID you are using and the absolute path to the svc-account you created)

const (
	saFile = "/path/to/recaptcha-svc.json"
	checkKey        = "6LenwLMaAAAAAJiGCftfhT2Iv-g5F_LSfKkj6B69"
	scoringKey      = "6Lefk7QaAAAAAJAtX1S7W_pXQz1tS2LLFAYXB9q-"
	assessmentName  = "yourassessmentname"
	parentProject   = "projects/your-project-id"
	recaptchaAction = "homepage"

Start the server

go run server.go

the server now listens for https traffic on port :8081. We are using a self-signed certificate here so you may want to load/trust this cert on the browser:

If you are using chrome, you should import both the root-ca.crt and tls-ca.crt…if you don’t mind cert warnings, ignore importing

Step 7

Now open up an incognito window and navigate to


(you may need to edit /etc/hosts and add a line local.esodemoapp2.com if you have DNS resolution issues)

Eventually (maybe a day later?), you will see stats on the key usage, etc



Thats it..

Now, some errors i ran into

a) kept seeing INVALID_REASON_UNSPECIFIED…what it turned out was i was using the wrong key type (v2,v3) (eg, checkbox key for scoring and vice versa)

…and probably more but this is a trivial sample..

This site supports webmentions. Send me a mention via this form.