This tutorial explains how to correctly create and configure Google reCAPTCHA when your main website is already registered and you need reCAPTCHA to work on a subdomain, such as an authentication or login service.

It covers:

• When to create a new key vs reuse an existing one
• How Google Cloud Platform (GCP) fits into reCAPTCHA
• How to handle subdomains properly
• Choosing the correct reCAPTCHA version
• Common mistakes and how to avoid them

This guide is written for real production use, especially for login, authentication, and secure forms.

---

1. Understanding the Problem Scenario

Your situation is:

• Main website: wizbrand.com
• Authentication or form running on: auth.wizbrand.com
• The website is already registered in Google Cloud Platform
• You reached the Google reCAPTCHA “Register a new site” page
• You are unsure:
  • Whether a new key is needed
  • How to handle subdomains
  • Which reCAPTCHA version to select
  • Whether a new GCP project is required

This confusion is very common, especially when authentication is moved to a subdomain.

---

2. Key Concept: Domains vs Google Cloud Projects

Before configuring anything, it is important to understand this clearly.

Google Cloud Project

• A Google Cloud project is only a container
• It does NOT restrict domains
• You can use the same project for multiple sites and subdomains

reCAPTCHA Site Configuration

• This is where domains are actually validated
• If a domain or subdomain is not listed here, reCAPTCHA will fail

This means:
You do not need a new Google Cloud project just because you added a subdomain.

---

3. When Do You Need a New reCAPTCHA Key?

You need a new key only if:

• You want to change reCAPTCHA version (for example, v3 to v2)
• You want separate analytics or security rules
• You want isolation between different applications

You do NOT need a new key just because:

• You added a subdomain
• You moved login to auth.wizbrand.com

In most authentication setups, reusing the same key is correct.

---

4. Choosing the Correct reCAPTCHA Version

Google offers two common options:

reCAPTCHA v3 (Score-Based)

• No checkbox
• Returns a score (0.0 to 1.0)
• Requires backend score logic
• Can block real users unintentionally
• Not ideal for login pages

reCAPTCHA v2 (Challenge-Based)

• Checkbox or challenge
• Clear user interaction
• More reliable for authentication
• Easier to debug and maintain

Recommendation for auth.wizbrand.com

For login, authentication, and security-sensitive forms:

Use reCAPTCHA v2 (Challenge)

This is the safest and most stable option for production auth systems.

---

5. Creating or Updating reCAPTCHA Configuration (Step-by-Step)

You are already on the correct page:
“Register a new site” in Google reCAPTCHA Admin.

Step 1: Label

This is only for your internal reference.

Recommended examples:

• Wizbrand Auth Login
• Wizbrand reCAPTCHA

This field does not affect functionality.

---

Step 2: Select reCAPTCHA Type

Choose:

• Challenge (v2)

Avoid score-based v3 for login unless you fully control backend scoring.

---

Step 3: Add Domains (Most Important Step)

You must explicitly add both the main domain and the subdomain.

Add:

• wizbrand.com
• auth.wizbrand.com

Important rules:

• Do not include https://
• Do not include trailing slashes
• Subdomains must be added explicitly

If auth.wizbrand.com is missing, reCAPTCHA will fail even if wizbrand.com works.

---

Step 4: Google Cloud Platform Project

Select your existing project:

• motoshare (or whichever project you already use)

No new project is required.

---

Step 5: Submit

After submitting, Google will generate:

• Site Key
• Secret Key

---

6. Understanding Site Key vs Secret Key

This distinction is critical.

Site Key

• Used in frontend (HTML, login page, Keycloak theme)
• Safe to expose publicly

Secret Key

• Used only on backend
• Must never be placed in frontend code
• Must be stored securely (environment variables)

If the secret key leaks, your captcha can be abused.

---

7. Using reCAPTCHA on auth.wizbrand.com

Frontend Usage

Use the same site key on both:

• wizbrand.com
• auth.wizbrand.com

The domain check is handled automatically by Google.

Backend Verification

No changes are needed when adding a subdomain.
The same secret key works across all allowed domains.

---

8. Important Caching and Browser Considerations

After adding a new domain:

• Clear browser cache
• Hard refresh the page
• If using CDN, purge cache
• If using server-side rendered templates, clear view cache

Many developers think reCAPTCHA is broken when it is actually cached HTML.

---

9. Common Mistakes That Cause reCAPTCHA Failure

These are the most frequent real-world issues:

• Adding only wizbrand.com but not auth.wizbrand.com
• Mixing v2 keys with v3 code
• Putting secret key in JavaScript
• Using wrong site key on subdomain
• Forgetting to save domain changes
• CDN caching old markup
• Using localhost without adding it to allowed domains

Avoiding these prevents 90% of captcha issues.

---

10. Keycloak / Auth System Specific Notes

If auth.wizbrand.com hosts:

• Keycloak
• OAuth login
• SSO gateway
• Central authentication service

Then:

• reCAPTCHA v2 is strongly recommended
• Domain must be explicitly listed
• Same site key can be reused
• Secret key must remain server-side

There is no CORS issue with reCAPTCHA itself.

---

11. Final Checklist Before Going Live

Before testing in production, verify:

• auth.wizbrand.com is listed in reCAPTCHA domains
• Correct reCAPTCHA version is selected
• Site key is used only in frontend
• Secret key is stored securely
• Cache is cleared
• Login page loads captcha correctly

If all of these are correct, reCAPTCHA will work reliably.

---