Capture the reCAPTCHA in WSO2 APIM

Enable the reCAPTCHA feature in WSO2 APIM 3.2.0 & 4.0.0

Saranki Magenthirarajah
5 min readMar 5, 2022

Prevention is better than precaution!

In the fast-growing internet era securing the applications, websites, user data, and credentials are pivotal. Numerous security mechanisms are being followed covering the purposes that vary from organization to organization. Such important security threats that have been faced by currently websites are spam and abuse. These security threats can be caused by automated software engaging in abusive activities on the websites. Such activities can malfunction your system, completely damage your system or even steal your valuable data and information which leads to business loss and reputation damage.

ReCaptcha: A quick look


reCAPTCHA is a free service provided by Google to perform bot tests in order to protect your websites from spam and abuse. Google has introduced various reCaptcha versions and they are as follows.

  • reCAPTCHA v1
  • reCAPTCHA v2
  • reCAPTCHA v3

reCAPTCHA v2 is the most commonly used version and in this blog, we’ll be trying out the reCAPTCHA v2 in WSO2 APIM 3.2.0 and WSO2 APIM 4.0.0 versions.


Please note that wso2am-3.2.0 has been used to demonstrate these steps in this blog post. But this is applicable for wso2am-4.0.0 as well. Kindly follow the below steps to get the ReCaptcha feature while logging into the APIM-3.2.0 publisher or developer or admin portal.

Step 1: Configuring reCAPTCHA API keys

1. Go to

2. If you are working with Google reCAPTCHA for the very first time then you will be directed to the following UI.

Fig 1: Google reCAPTCHA registration page

If you have already registered to use reCAPTCHA in any of your applications before, then you will be directed to the following analytics page. On the right top corner, you get a “+” symbol and if you click on that, you will be directed to the UI shown in Fig 1.

Fig 2: Google reCAPTCHA analytics page

3. The following details should be filled out in the presented UI. The purpose of each of these elements is listed below.

  • Label: Use a label that will make it easy for you to identify the site in the future.
  • Recaptcha type: Choose the type of reCAPTCHA for this site key. A site key only works with a single reCAPTCHA site type. See Site Types for more details. For this blog, I have picked reCAPTCHA v2 → “I’m not a robot” Checkbox.
  • Domains: The google registration is restricted to the domains you enter here, plus any subdomains. In other words, a registration for also registers A valid domain requires a host and must not include any path, port, query, or fragment. Since I’ll be running the APIM with the hostname “localhost” I have given the “Domains” value as “localhost”.
  • Send alerts to owners: Get alerts if Google detects problems with your site, such as misconfigurations or an increase in suspicious traffic.
Fig 3: Google reCAPTCHA filled registration page

4. Click on “Submit”

5. In the next UI, you will get the site key and the secret key as shown below. Copy those keys.

Fig 4: Google reCAPTCHA keys

Step 2: Configure the APIM 3.2.0 to enable the reCAPTCHA feature for publisher, devportal, and admin portal logins

1. Navigate to {APIM-Home}/repository/conf/deployment.toml and add the following configurations. Please replace the site key and secret key with the ones you have generated previously.

#Enable Google reCAPTCHA
enabled= true

#reCaptcha API URL

#reCaptcha verification URL

#reCaptcha site key

#reCaptcha secret key

2. Re-start the APIM server.

3. Log in to the carbon management console.

4. Navigate to Main → Identity → Identity Providers → Resident → Login Policies → Captcha for SSO Login

5. You will be able to see the following section.

Fig 5: WSO2 carbon management console UI to configure the resident identity provider with the reCAPTCHA enabled logins

6. Tick the “Enable captcha always” and if required you can tick the “Enable captcha after the Max failed attempts” check box as well.

7. Click on “Update”.

Step 3: Testing

  1. By default, the WSO2 APIM publisher portal, developer portal, and admin portal login pages will be displayed as shown below without the reCAPTCHA.
Fig 6: Publisher/Developer/Admin portal default login UI

2. In WSO2 APIM 3.2.0 publisher, devportal, and admin portal, you will be able to see the ReCaptcha feature as shown below once you enable it as instructed above.

Fig 7: Publisher/Developer/Admin portal login UI after enabling the reCAPTCHA

3. If you try to log in without selecting the “I’m not a robot” reCAPTCHA box you will not be able to log in to the relevant portal and will get the following error message as well.

Fig 8: Publisher/Developer/Admin portal login UI error message without selecting the reCAPTCHA box

Wind Up!

I hope that this was a useful blog for enabling the reCAPTCHA feature in wso2am 3.2.0 and wso2am-4.0.0! See you all soon in another blog! Till then keep safe and keep on learning!!!

Happy Learning!