recaptcha

README

recaptcha-go

Google reCAPTCHA v2 & v3 form submission verification in golang.

Usage

The API has changed form last version hence the new major version change.
Old API is still available using the package gopkg.in/ezzarghili/recaptcha-go.v2 although it does not provide all options available in this version.
As always install the package in your environment by using a stable API version, see latest version in releases page.

go get -u gopkg.in/ezzarghili/recaptcha-go.v4 

recaptcha v2 API

import "gopkg.in/ezzarghili/recaptcha-go.v4"
func main(){
    captcha, _ := recaptcha.NewReCAPTCHA(recaptchaSecret, recaptcha.V2, 10 * time.Second) // for v2 API get your secret from https://www.google.com/recaptcha/admin
}

Now everytime you need to verify a V2 API client with no special options request use.

err := captcha.Verify(recaptchaResponse)
if err != nil {
    // do something with err (log?)
    // Example check error codes array if they exist: (err.(*recaptcha.Error)).ErrorCodes
}
// proceed

For specific options use the VerifyWithOptions method
Available options for the v2 api are:

  Hostname       string
  ApkPackageName string
  ResponseTime   time.Duration
  RemoteIP       string

Other v3 options are ignored and method will return nil when succeeded.

err := captcha.VerifyWithOptions(recaptchaResponse, VerifyOption{RemoteIP: "123.123.123.123"})
if err != nil {
    // do something with err (log?)
    // Example check error codes array if they exist: (err.(*recaptcha.Error)).ErrorCodes
}
// proceed

recaptcha v3 API

import "gopkg.in/ezzarghili/recaptcha-go.v4"
func main(){
    captcha, _ := recaptcha.NewReCAPTCHA(recaptchaSecret, recaptcha.V3, 10 * time.Second) // for v3 API use https://g.co/recaptcha/v3 (apperently the same admin UI at the time of writing)
}

Now everytime you need to verify a V3 API client with no special options request use.

err := captcha.Verify(recaptchaResponse)
if err != nil {
    // do something with err (log?)
}
// proceed

Note that as recaptcha v3 use score for challenge validation, if no threshold option is set the default value is 0.5

For specific options use the VerifyWithOptions method.
Available options for the v3 api are:

   Threshold      float32
   Action         string
   Hostname       string
   ApkPackageName string
   ResponseTime   time.Duration
   RemoteIP       string

err := captcha.VerifyWithOptions(recaptchaResponse, VerifyOption{Action: "hompage", Threshold: 0.8})
if err != nil {
    // do something with err (log?)
}
// proceed

While recaptchaResponse is the form value with name g-recaptcha-response sent back by recaptcha server and set for you in the form when a user answers the challenge.

Both recaptcha.Verify and recaptcha.VerifyWithOptions return a error or nil if successful.

Use the error to check for issues with the secret, connection with the server, options mismatches and incorrect solution.

This version made timeout explcit to make sure users have the possiblity to set the underling http client timeout suitable for their implemetation.

Run Tests

Use the standard go means of running test. You can also check examples of usage in the tests.

go test

Issues with this library

If you have some problems with using this library, bug reports or enhancement please open an issue in the issues tracker.

License

Let's go with something permitive should we?

MIT

Documentation

Index

• Constants
• type Error
  • func (e *Error) Error() string
• type ReCAPTCHA
  • func NewReCAPTCHA(ReCAPTCHASecret string, version VERSION, timeout time.Duration) (ReCAPTCHA, error)
  • func (r *ReCAPTCHA) Verify(challengeResponse string) error
  • func (r *ReCAPTCHA) VerifyWithOptions(challengeResponse string, options VerifyOption) error
• type VERSION
• type VerifyOption

Constants

const (
	// V2 recaptcha api v2
	V2 VERSION = iota
	// V3 recaptcha api v3, more details can be found here : https://developers.google.com/recaptcha/docs/v3
	V3
	// DefaultThreshold Default minimin score when using V3 api
	DefaultThreshold float32 = 0.5
)

Types

type Error

type Error struct {

	// ErrorCodes contains any error codes from the recaptcha response.
	ErrorCodes []string
	// RequestError is true if the verify request to recaptcha failed.
	RequestError bool
	// contains filtered or unexported fields
}

Error custom error to pass ErrorCodes and RequestError to user.

func (*Error) Error

func (e *Error) Error() string

type ReCAPTCHA

type ReCAPTCHA struct {
	Secret        string
	ReCAPTCHALink string
	Version       VERSION
	Timeout       time.Duration
	// contains filtered or unexported fields
}

ReCAPTCHA recpatcha holder struct, make adding mocking code simpler.

func NewReCAPTCHA

func NewReCAPTCHA(ReCAPTCHASecret string, version VERSION, timeout time.Duration) (ReCAPTCHA, error)

NewReCAPTCHA new ReCAPTCHA instance if version is set to V2 uses recatpcha v2 API, get your secret from https://www.google.com/recaptcha/admin

if version is set to V2 uses recatpcha v2 API, get your secret from https://g.co/recaptcha/v3

func (*ReCAPTCHA) Verify

func (r *ReCAPTCHA) Verify(challengeResponse string) error

Verify returns `nil` if no error and the client solved the challenge correctly

func (*ReCAPTCHA) VerifyWithOptions

func (r *ReCAPTCHA) VerifyWithOptions(challengeResponse string, options VerifyOption) error

VerifyWithOptions returns `nil` if no error and the client solved the challenge correctly and all options are matching `Threshold` and `Action` are ignored when using V2 version

type VERSION

type VERSION int8

VERSION the recaptcha api version

type VerifyOption

type VerifyOption struct {
	Threshold      float32 // ignored in v2 recaptcha
	Action         string  // ignored in v2 recaptcha
	Hostname       string
	ApkPackageName string
	ResponseTime   time.Duration
	RemoteIP       string
}

VerifyOption verification options expected for the challenge