reCAPTCHA
Author: Jason L Perry (http://ambethia.com)
Copyright: Copyright (c) 2007-2013 Jason L Perry
License: MIT
Info: https://github.com/ambethia/recaptcha
Bugs: https://github.com/ambethia/recaptcha/issues
This gem provides helper methods for the reCAPTCHA API. In your
views you can use the recaptcha_tags
method to embed the needed javascript, and you can validate
in your controllers with verify_recaptcha
or verify_recaptcha!
, which raises an error on
failure.
Table of Contents
- Obtaining a key
- Rails Installation
- Sinatra / Rack / Ruby Installation
- reCAPTCHA V2 API & Usage
- reCAPTCHA V3 API & Usage
- I18n Support
- Testing
- Alternative API Key Setup
Obtaining a key
Go to the reCAPTCHA admin console to obtain a reCAPTCHA API key.
The reCAPTCHA type(s) that you choose for your key will determine which methods to use below.
reCAPTCHA type | Methods to use | Description |
---|---|---|
v3 | recaptcha_v3 |
Verify requests with a score |
v2 Checkbox ("I'm not a robot" Checkbox) |
recaptcha_tags |
Validate requests with the "I'm not a robot" checkbox |
v2 Invisible (Invisible reCAPTCHA badge) |
invisible_recaptcha_tags |
Validate requests in the background |
Note: You can only use methods that match your key's type. You cannot use v2 methods with a v3
key or use recaptcha_tags
with a v2 Invisible key, for example. Otherwise you will get an
error like "Invalid key type" or "This site key is not enabled for the invisible captcha."
Note: Enter localhost
or 127.0.0.1
as the domain if using in development with localhost:3000
.
Rails Installation
If you are having issues with Rails 7, Turbo, and Stimulus, make sure to check this Wiki page!
gem "recaptcha"
You can keep keys out of the code base with environment variables or with Rails secrets.
In development, you can use the dotenv gem. (Make sure to add it above gem 'recaptcha'
.)
See Alternative API key setup for more ways to configure or override keys. See also the Configuration documentation.
export RECAPTCHA_SITE_KEY = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
export RECAPTCHA_SECRET_KEY = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
If you have an Enterprise API key:
export RECAPTCHA_ENTERPRISE = 'true'
export RECAPTCHA_ENTERPRISE_API_KEY = 'AIzvFyE3TU-g4K_Kozr9F1smEzZSGBVOfLKyupA'
export RECAPTCHA_ENTERPRISE_PROJECT_ID = 'my-project'
Add recaptcha_tags
to the forms you want to protect:
<%= form_for @foo do |f| %>
# …
<%= recaptcha_tags %>
# …
<% end %>
Then, add verify_recaptcha
logic to each form action that you've protected:
# app/controllers/users_controller.rb
@user = User.new(params[:user].permit(:name))
if verify_recaptcha(model: @user) && @user.save
redirect_to @user
else
render 'new'
end
Please note that this setup uses reCAPTCHA_v2
. For a recaptcha_v3
use, please refer to reCAPTCHA_v3 setup
.
Sinatra / Rack / Ruby installation
See sinatra demo for details.
- add
gem 'recaptcha'
toGemfile
- set env variables
include Recaptcha::Adapters::ViewMethods
where you needrecaptcha_tags
include Recaptcha::Adapters::ControllerMethods
where you needverify_recaptcha
reCAPTCHA v2 API and Usage
recaptcha_tags
Use this when your key's reCAPTCHA type is "v2 Checkbox".
The following options are available:
Option | Description |
---|---|
:theme |
Specify the theme to be used per the API. Available options: dark and light . (default: light ) |
:ajax |
Render the dynamic AJAX captcha per the API. (default: false ) |
:site_key |
Override site API key from configuration |
:error |
Override the error code returned from the reCAPTCHA API (default: nil ) |
:size |
Specify a size (default: nil ) |
:nonce |
Optional. Sets nonce attribute for script. Can be generated via SecureRandom.base64(32) . (default: nil ) |
:id |
Specify an html id attribute (default: nil ) |
:callback |
Optional. Name of success callback function, executed when the user submits a successful response |
:expired_callback |
Optional. Name of expiration callback function, executed when the reCAPTCHA response expires and the user needs to re-verify. |
:error_callback |
Optional. Name of error callback function, executed when reCAPTCHA encounters an error (e.g. network connectivity) |
:noscript |
Include <noscript> content (default: true ) |
JavaScript resource (api.js) parameters:
Option | Description |
---|---|
:onload |
Optional. The name of your callback function to be executed once all the dependencies have loaded. (See explicit rendering) |
:render |
Optional. Whether to render the widget explicitly. Defaults to onload , which will render the widget in the first g-recaptcha tag it finds. (See explicit rendering) |
:hl |
Optional. Forces the widget to render in a specific language. Auto-detects the user's language if unspecified. (See language codes) |
:script |
Alias for :external_script . If you do not need to add a script tag by helper you can set the option to false . It's necessary when you add a script tag manualy (default: true ). |
:external_script |
Set to false to avoid including a script tag for the external api.js resource. Useful when including multiple recaptcha_tags on the same page. |
:script_async |
Set to false to load the external api.js resource synchronously. (default: true ) |
:script_defer |
Set to true to defer loading of external api.js until HTML documen has been parsed. (default: true ) |
Any unrecognized options will be added as attributes on the generated tag.
You can also override the html attributes for the sizes of the generated textarea
and iframe
elements, if CSS isn't your thing. Inspect the source of recaptcha_tags
to see these options.
Note that you cannot submit/verify the same response token more than once or you will get a
timeout-or-duplicate
error code. If you need reset the captcha and generate a new response token,
then you need to call grecaptcha.reset()
.
verify_recaptcha
This method returns true
or false
after processing the response token from the reCAPTCHA widget.
This is usually called from your controller, as seen above.
Passing in the ActiveRecord object via model: object
is optional. If you pass a model
—and the
captcha fails to verify—an error will be added to the object for you to use (available as
object.errors
).
Why isn't this a model validation? Because that violates MVC. You can use it like this, or how ever you like.
Some of the options available:
Option | Description |
---|---|
:model |
Model to set errors. |
:attribute |
Model attribute to receive errors. (default: :base ) |
:message |
Custom error message. |
:secret_key |
Override the secret API key from the configuration. |
:enterprise_api_key |
Override the Enterprise API key from the configuration. |
:enterprise_project_id |
Override the Enterprise project ID from the configuration. |
:timeout |
The number of seconds to wait for reCAPTCHA servers before give up. (default: 3 ) |
:response |
Custom response parameter. (default: params['g-recaptcha-response-data'] ) |
:hostname |
Expected hostname or a callable that validates the hostname, see domain validation and hostname docs. (default: nil , but can be changed by setting config.hostname ) |
:env |
Current environment. The request to verify will be skipped if the environment is specified in configuration under skip_verify_env |
:json |
Boolean; defaults to false; if true, will submit the verification request by POST with the request data in JSON |
invisible_recaptcha_tags
Use this when your key's reCAPTCHA type is "v2 Invisible".
For more information, refer to: Invisible reCAPTCHA.
This is similar to recaptcha_tags
, with the following additional options that are only available
on invisible_recaptcha_tags
:
Option | Description |
---|---|
:ui |
The type of UI to render for this "invisible" widget. (default: :button ):button : Renders a <button type="submit"> tag with options[:text] as the button text.:invisible : Renders a <div> tag.:input : Renders a <input type="submit"> tag with options[:text] as the button text. |
:text |
The text to show for the button. (default: "Submit" ) |
:inline_script |
If you do not need this helper to add an inline script tag, you can set the option to false (default: true ). |
It also accepts most of the options that recaptcha_tags
accepts, including the following:
Option | Description |
---|---|
:site_key |
Override site API key from configuration |
:nonce |
Optional. Sets nonce attribute for script tag. Can be generated via SecureRandom.base64(32) . (default: nil ) |
:id |
Specify an html id attribute (default: nil ) |
:script |
Same as setting both :inline_script and :external_script . If you only need one or the other, use :inline_script and :external_script instead. |
:callback |
Optional. Name of success callback function, executed when the user submits a successful response |
:expired_callback |
Optional. Name of expiration callback function, executed when the reCAPTCHA response expires and the user needs to re-verify. |
:error_callback |
Optional. Name of error callback function, executed when reCAPTCHA encounters an error (e.g. network connectivity) |
JavaScript resource (api.js) parameters:
Option | Description |
---|---|
:onload |
Optional. The name of your callback function to be executed once all the dependencies have loaded. (See explicit rendering) |
:render |
Optional. Whether to render the widget explicitly. Defaults to onload , which will render the widget in the first g-recaptcha tag it finds. (See explicit rendering) |
:hl |
Optional. Forces the widget to render in a specific language. Auto-detects the user's language if unspecified. (See language codes) |
:external_script |
Set to false to avoid including a script tag for the external api.js resource. Useful when including multiple recaptcha_tags on the same page. |
:script_async |
Set to false to load the external api.js resource synchronously. (default: true ) |
:script_defer |
Set to false to defer loading of external api.js until HTML documen has been parsed. (default: true ) |
With a single form on a page
- The
invisible_recaptcha_tags
generates a submit button for you.
<%= form_for @foo do |f| %>
# ... other tags
<%= invisible_recaptcha_tags text: 'Submit form' %>
<% end %>
Then, add verify_recaptcha
to your controller as seen above.
With multiple forms on a page
- You will need a custom callback function, which is called after verification with Google's reCAPTCHA service. This callback function must submit the form. Optionally,
invisible_recaptcha_tags
currently implements a JS function calledinvisibleRecaptchaSubmit
that is called when nocallback
is passed. Should you wish to overrideinvisibleRecaptchaSubmit
, you will need to useinvisible_recaptcha_tags script: false
, see lib/recaptcha/client_helper.rb for details. - The
invisible_recaptcha_tags
generates a submit button for you.
<%= form_for @foo, html: {id: 'invisible-recaptcha-form'} do |f| %>
# ... other tags
<%= invisible_recaptcha_tags callback: 'submitInvisibleRecaptchaForm', text: 'Submit form' %>
<% end %>
// app/assets/javascripts/application.js
var submitInvisibleRecaptchaForm = function () {
document.getElementById("invisible-recaptcha-form").submit();
};
Finally, add verify_recaptcha
to your controller as seen above.
Programmatically invoke
- Specify
ui
option
<%= form_for @foo, html: {id: 'invisible-recaptcha-form'} do |f| %>
# ... other tags
<button type="button" id="submit-btn">
Submit
</button>
<%= invisible_recaptcha_tags ui: :invisible, callback: 'submitInvisibleRecaptchaForm' %>
<% end %>
// app/assets/javascripts/application.js
document.getElementById('submit-btn').addEventListener('click', function (e) {
// do some validation
if(isValid) {
// call reCAPTCHA check
grecaptcha.execute();
}
});
var submitInvisibleRecaptchaForm = function () {
document.getElementById("invisible-recaptcha-form").submit();
};
reCAPTCHA v3 API and Usage
The main differences from v2 are:
- you must specify an action in both frontend and backend
- you can choose the minimum score required for you to consider the verification a success (consider the user a human and not a robot)
- reCAPTCHA v3 is invisible (except for the reCAPTCHA badge) and will never interrupt your users; you have to choose which scores are considered an acceptable risk, and choose what to do (require two-factor authentication, show a v3 challenge, etc.) if the score falls below the threshold you choose
For more information, refer to the v3 documentation.
Examples
With v3, you can let all users log in without any intervention at all if their score is above some threshold, and only show a v2 checkbox recaptcha challenge (fall back to v2) if it is below the threshold:
…
<% if @show_checkbox_recaptcha %>
<%= recaptcha_tags %>
<% else %>
<%= recaptcha_v3(action: 'login', site_key: ENV['RECAPTCHA_SITE_KEY_V3']) %>
<% end %>
…
# app/controllers/sessions_controller.rb
def create
success = verify_recaptcha(action: 'login', minimum_score: 0.5, secret_key: ENV['RECAPTCHA_SECRET_KEY_V3'])
checkbox_success = verify_recaptcha unless success
if success || checkbox_success
# Perform action
else
if !success
@show_checkbox_recaptcha = true
end
render 'new'
end
end
(You can also find this example in the demo app.)
Another example:
<%= form_for @user do |f| %>
…
<%= recaptcha_v3(action: 'registration') %>
…
<% end %>
# app/controllers/users_controller.rb
def create
@user = User.new(params[:user].permit(:name))
recaptcha_valid = verify_recaptcha(model: @user, action: 'registration')
if recaptcha_valid
if @user.save
redirect_to @user
else
render 'new'
end
else
# Score is below threshold, so user may be a bot. Show a challenge, require multi-factor
# authentication, or do something else.
render 'new'
end
end
recaptcha_v3
Adds an inline script tag that calls grecaptcha.execute
for the given site_key
and action
and
calls the callback
with the resulting response token. You need to verify this token with
verify_recaptcha
in your controller in order to get the
score.
By default, this inserts a hidden <input type="hidden" class="g-recaptcha-response">
tag. The
value of this input will automatically be set to the response token (by the default callback
function). This lets you include recaptcha_v3
within a <form>
tag and have it automatically
submit the token as part of the form submission.
Note: reCAPTCHA actually already adds its own hidden tag, like <textarea
id="g-recaptcha-response-data-100000" name="g-recaptcha-response-data" class="g-recaptcha-response">
,
immediately ater the reCAPTCHA badge in the bottom right of the page — but since it is not inside of
any <form>
element, and since it already passes the token to the callback, this hidden textarea
isn't helpful to us.
If you need to submit the response token to the server in a different way than via a regular form
submit, such as via Ajax or fetch
,
then you can either:
- just extract the token out of the hidden
<input>
or<textarea>
(both of which will have a predictable name/id), likedocument.getElementById('g-recaptcha-response-data-my-action').value
, or - write and specify a custom
callback
function. You may also want to passelement: false
if you don't have a use for the hidden input element.
Note that you cannot submit/verify the same response token more than once or you
will get a timeout-or-duplicate
error code. If you need reset the captcha and
generate a new response token, then you need to call grecaptcha.execute(…)
or
grecaptcha.enterprise.execute(…)
again. This helper provides a JavaScript
method (for each action) named executeRecaptchaFor{action}
to make this
easier. That is the same method that is invoked immediately. It simply calls
grecaptcha.execute
or grecaptcha.enterprise.execute
again and then calls the
callback
function with the response token.
You will also get a timeout-or-duplicate
error if too much time has passed between getting the
response token and verifying it. This can easily happen with large forms that take the user a couple
minutes to complete. Unlike v2, where you can use the expired-callback
to be notified when the
response expires, v3 appears to provide no such callback. See also
1 and
2.
To deal with this, it is recommended to call the "execute" in your form's submit handler (or
immediately before sending to the server to verify if not using a form) rather than using the
response token that gets generated when the page first loads. The executeRecaptchaFor{action}
function mentioned above can be used if you want it to invoke a callback, or the
executeRecaptchaFor{action}Async
variant if you want a Promise
that you can await
. See
demo/rails/app/views/v3_captchas/index.html.erb
for an example of this.
This helper is similar to the recaptcha_tags
/invisible_recaptcha_tags
helpers
but only accepts the following options:
Option | Description |
---|---|
:site_key |
Override site API key |
:action |
The name of the reCAPTCHA action. Actions are not case-sensitive and may only contain alphanumeric characters, slashes, and underscores, and must not be user-specific. |
:nonce |
Optional. Sets nonce attribute for script. Can be generated via SecureRandom.base64(32) . (default: nil ) |
:callback |
Name of callback function to call with the token. When element is :input , this defaults to a function named setInputWithRecaptchaResponseTokenFor#{sanitize_action(action)} that sets the value of the hidden input to the token. |
:id |
Specify a unique id attribute for the <input> element if using element: :input . (default: "g-recaptcha-response-data-" + action ) |
:name |
Specify a unique name attribute for the <input> element if using element: :input . (default: g-recaptcha-response-data[action] ) |
:script |
Same as setting both :inline_script and :external_script . (default: true ). |
:inline_script |
If true , adds an inline script tag that calls grecaptcha.execute for the given site_key and action and calls the callback with the resulting response token. Pass false if you want to handle calling grecaptcha.execute yourself. (default: true ) |
:element |
The element to render, if any (default: :input ):input : Renders a hidden <input type="hidden"> tag. The value of this will be set to the response token by the default setInputWithRecaptchaResponseTokenFor{action} callback.false : Doesn't render any tag. You'll have to add a custom callback that does something with the token. |
:turbolinks |
If true , calls the js function which executes reCAPTCHA after all the dependencies have been loaded. This cannot be used with the js param :onload . This makes reCAPTCHAv3 usable with turbolinks. |
:ignore_no_element |
If true , adds null element checker for forms that can be removed from the page by javascript like modals with forms. (default: true) |
JavaScript resource (api.js) parameters:
Option | Description |
---|---|
:onload |
Optional. The name of your callback function to be executed once all the dependencies have loaded. (See explicit rendering) |
:external_script |
Set to false to avoid including a script tag for the external api.js resource. Useful when including multiple recaptcha_tags on the same page. |
:script_async |
Set to true to load the external api.js resource asynchronously. (default: false ) |
:script_defer |
Set to true to defer loading of external api.js until HTML documen has been parsed. (default: false ) |
If using element: :input
, any unrecognized options will be added as attributes on the generated
<input>
element.
verify_recaptcha
(use with v3)
This works the same as for v2, except that you may pass an action
and minimum_score
if you wish
to validate that the action matches or that the score is above the given threshold, respectively.
result = verify_recaptcha(action: 'action/name')
Option | Description |
---|---|
:action |
The name of the reCAPTCHA action that we are verifying. Set to false or nil to skip verifying that the action matches. |
:minimum_score |
Provide a threshold to meet or exceed. Threshold should be a float between 0 and 1 which will be tested as score >= minimum_score . (Default: nil ) |
Multiple actions on the same page
According to https://developers.google.com/recaptcha/docs/v3#placement,
Note: You can execute reCAPTCHA as many times as you'd like with different actions on the same page.
You will need to verify each action individually with a separate call to verify_recaptcha
.
result_a = verify_recaptcha(action: 'a')
result_b = verify_recaptcha(action: 'b')
Because the response tokens for multiple actions may be submitted together in the same request, they
are passed as a hash under params['g-recaptcha-response-data']
with the action as the key.
It is recommended to pass external_script: false
on all but one of the calls to
recaptcha
since you only need to include the script tag once for a given site_key
.
recaptcha_reply
After verify_recaptcha
has been called, you can call recaptcha_reply
to get the raw reply from recaptcha. This can allow you to get the exact score returned by recaptcha should you need it.
if verify_recaptcha(action: 'login')
redirect_to @user
else
score = recaptcha_reply['score']
Rails.logger.warn("User #{@user.id} was denied login because of a recaptcha score of #{score}")
render 'new'
end
recaptcha_reply
will return nil
if the the reply was not yet fetched.
I18n support
reCAPTCHA supports the I18n gem (it comes with English translations)
To override or add new languages, add to config/locales/*.yml
# config/locales/en.yml
en:
recaptcha:
errors:
verification_failed: 'reCAPTCHA was incorrect, please try again.'
recaptcha_unreachable: 'reCAPTCHA verification server error, please try again.'
Testing
By default, reCAPTCHA is skipped in "test" and "cucumber" env. To enable it during test:
Recaptcha.configuration.skip_verify_env.delete("test")
Alternative API key setup
Recaptcha.configure
# config/initializers/recaptcha.rb
Recaptcha.configure do |config|
config.site_key = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
config.secret_key = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
# Uncomment the following line if you are using a proxy server:
# config.proxy = 'http://myproxy.com.au:8080'
# Uncomment the following lines if you are using the Enterprise API:
# config.enterprise = true
# config.enterprise_api_key = 'AIzvFyE3TU-g4K_Kozr9F1smEzZSGBVOfLKyupA'
# config.enterprise_project_id = 'my-project'
end
Recaptcha.with_configuration
For temporary overwrites (not thread-safe).
Recaptcha.with_configuration(site_key: '12345') do
# Do stuff with the overwritten site_key.
end
Per call
Pass in keys as options at runtime, for code base with multiple reCAPTCHA setups:
site_key: '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
# and
verify_recaptcha secret_key: '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
hCaptcha support
hCaptcha is an alternative service providing reCAPTCHA API.
To use hCaptcha:
- Set a site and a secret key as usual
- Set two options in
verify_url
andapi_service_url
pointing to hCaptcha API endpoints. - Disable a response limit check by setting a
response_limit
to the large enough value (reCAPTCHA is limited by 4000 characters). - It is not required to change a parameter name as official docs suggest because API handles standard
g-recaptcha
for compatibility.
# config/initializers/recaptcha.rb
Recaptcha.configure do |config|
config.site_key = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
config.secret_key = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
config.verify_url = 'https://hcaptcha.com/siteverify'
config.api_server_url = 'https://hcaptcha.com/1/api.js'
config.response_limit = 100000
end
hCaptcha uses a scoring system (higher number more likely to be a bot) which is inverse of the reCaptcha scoring system (lower number more likely to be a bot). As such, a maximum_score
attribute is provided for use with hCaptcha.
result = verify_recaptcha(maximum_score: 0.7)
Option | Description |
---|---|
:maximum_score |
Provide a threshold to meet or fall below. Threshold should be a float between 0 and 1 which will be tested as score <= maximum_score . (Default: nil ) |
Misc
- Check out the wiki and leave whatever you found valuable there.
- Add multiple widgets to the same page
- Use Recaptcha with Devise