Skip to content

Setting Up ReCaptcha

reCaptcha is a free service provided by Google that can be used for protection against spam or other forms of internet abuse by verifying whether a user is a human or a robot. It comes in the form of a widget. The following section guides you through setting up reCaptcha with the WSO2 Identity Server and how to use it in different scenarios.

How it works

First, you will need to register and create an API key pair for the required domain. The key pair consists of a site key and secret. The site key is what is used when a reCaptcha widget is displayed on a page. After verification, a new parameter called g-recaptcha-response appears on the form which the user submits. From the server side, you can verify the submitted captcha response by calling the Google API with the secret key.

Follow the steps provided below to configure this.

Configuring reCaptcha API keys

  1. Go to

  2. You will see the following window. Fill in the fields to register your identity server domain and click Register. The following are sample values:

    • Label: WSO2 Identity Server
    • Select the reCAPTCHA V2 or Invisible reCAPTCHA option.
    • Domains:

    configuring-recaptcha-api-keys 3. Take note of the site key and secret that you receive. note-site-key-secret 4. Open the deployment.toml file located in the <IS_HOME>/repository/conf/ directory and add the following configurations.

    # Google reCAPTCHA settings
    # Enable Google reCAPTCHA
    enabled= true
    # reCaptcha API URL
    # reCaptcha verification URL
    # reCaptcha site key
    # reCaptcha secret key


    If you have additional authorization endpoints, you need to include the URL paths of these endpoints. Here, url_path is the URL without the host parameters.


    Below is an example of how to include the URL paths of additional authorization end points.

  3. Restart the WSO2 IS server.

You have successfully set up reCaptcha for your site. You can now configure reCaptcha with any of the following: