Integrate Cloudflare Turnstile in Vue.js

Introduction

In a blog post here, we explained how to integrate hCaptcha into a Vue.js application and why it might be necessary. In this post, we will focus on how to integrate Cloudflare Turnstile into a Vue.js application.

Cloudflare Turnstile is an advanced CAPTCHA alternative designed to enhance user experience by minimizing disruptions. Unlike traditional CAPTCHAs that require users to solve puzzles, Turnstile often operates invisibly, validating legitimate users without interaction. It prioritizes privacy by not tracking users across sites or collecting personal data. Integrated into Cloudflare's global network, Turnstile offers improved performance and faster load times. It also enhances accessibility by reducing reliance on visual challenges, making it more user-friendly for individuals with disabilities.

Advantages of Cloudflare Turnstile

User experience: Turnstile is designed to be less intrusive and often invisible to users. It can validate legitimate users without requiring them to complete puzzles or challenges, which can improve user experience.
Privacy: Turnstile is built with privacy in mind. It doesn't track users across sites or collect personal data, which can be a concern with some CAPTCHA systems.
Performance: Turnstile is integrated into Cloudflare's global network, which can lead to faster load times and better performance, especially for sites already using Cloudflare services.
Accessibility: By often not requiring visual challenges, Turnstile can be more accessible to users with disabilities.
Integration: For websites already using Cloudflare, integrating Turnstile can be simpler and more streamlined.
Cost: Turnstile offers a free tier with generous usage limits, which can be more cost-effective for some sites.
Machine learning approach: Turnstile uses advanced techniques to distinguish between humans and bots without relying solely on traditional CAPTCHA methods.

Steps to integrate cloudflare turnstile into a vuejs application

There are two ways to configure Cloudflare Turnstile in a web application: implicit and explicit. In implicit rendering, the Turnstile JavaScript file expects a div with the cf-turnstile class somewhere on the page and automatically renders the CAPTCHA inside this div without any extra code. However, this approach may not work if the component rendering this div is not available during the initial loading of a single-page application (SPA) when the Turnstile code is executed automatically. This is where explicit rendering comes into play, as it allows you to define precisely when you want to execute the Turnstile script code. Explicit rendering is what we will cover in this post.

Add a site in Cloudflare console

Log on to Cloudflare console, navigate to Turnstile section and add a site for your vuejs application. You can adjust widget mode and other settings as per your requirements. Make a note of Site Key and Secret Key for the newly added site.

Update application code

First add the turnstile script under the <head> tag of your index.html file -

<head>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit" async defer></script>
</head>

As you can see above, we have added render=explicit query string to the script url to indicate that explicit rendering should be used to display the CAPTCHA.

Add a div on a page where you want to render the turnstile CAPTCHA -

<template>
    <div id="turnstile"></div>
</template>

<script setup>
</script>

Value of id attribute can be anything. Make sure you use same value in the next step too.

Add the logic under onMounted() hook to render the CAPTCHA explicitly -

<script setup>
    const captchaToken = ref('')

    onMounted(() => {
      turnstile.render(
         '#turnstile', 
         {
            sitekey: '<turstile_site_key>',
            callback: function(token) {
               captchaToken.value = token
            }
         })
   })
</script>

We are using the turnstile.render method to render the CAPTCHA explicitly. The first parameter is the ID of the div element where we want to render the CAPTCHA. The second parameter is an object with two keys: sitekey and callback. Update the sitekey value with the site key you received after adding your application in the Cloudflare console. The callback function runs when the CAPTCHA challenge is successfully solved. It receives a token generated after the successful challenge as an input parameter.

Now you can pass this token as a header to an api which you wants to protect using turnstile CAPTCHA.

Validate token in the backend

Following is a sample code which you can use to validate the turnstile token in the backend -

const secret = // secret key from cloudflare console
const token = // retrieve token from the header

console.log('Captcha token : ' + token)

const validateCaptchaResponse = await fetch(
   'https://challenges.cloudflare.com/turnstile/v0/siteverify',
   {
      method: 'POST',
      headers: {
         'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: `secret=${encodeURIComponent(secret)}&response=${encodeURIComponent(token)}`
   }
)

console.log('Validate captcha status code : ' + validateCaptchaResponse.status)
const validateCaptchaResponseBody = await validateCaptchaResponse.json()
console.log('Validate captcha response : ' + JSON.stringify(validateCaptchaResponseBody))

if(validateCaptchaResponseBody.success) {
   // continue execution
} else {
   // return response with a status code (e.g. 403) indicating failure to execute the target endpoint
}

secret - It is the secret key from cloudflare console which is generated in addition to site key when an application is added under Turnstile section.
token - This is the token which was generated on UI side and passed as a header to the backend.

We will need to post these two to challenges.cloudflare.com/turnstile/v0/site.. endpoint in order to validate the token.

After following all the above steps, you will have Cloudflare Turnstile integrated into your vuejs application.

MechCloud Academy