Add Bot Detection to Custom Login Pages

If you build a custom login page using the auth0.js library, you can enable Bot Detection to render a CAPTCHA step in scenarios when a request is determined to be high risk by Auth0.

Your custom login form code must handle scenarios where the user is asked to pass a CAPTCHA step. If you don't account for this scenario, your application may cause an error.

Auth0 provides a template for you to use with code to handle high-risk logins.

1. Go to Dashboard > Branding > Universal Login and select Classic.

2. Click the Login tab and enable the Customize Login Page switch if it is not already enabled.

3. Locate the Default Templates drop-down menu and select Custom Login Form.

   

4. Use the provided template to begin customizing your login page.

   We recommend using version control software to manage the source code of your Custom Login Pages. To learn more, read Classic Login Page Version Control.

5. If you are not using version control software, you can replace the template with your source code directly in the Dashboard.

6. Select Preview to see your new form.

7. Select Save Changes.

If you'd like to support Bot Detection, you must use version 9.28 or higher of the auth0.js library.

<script src="https://cdn.auth0.com/js/auth0/9.28/auth0.min.js"></script>

1. Add an element to render the CAPTCHA below your password input and above your sign-up and login buttons. For example: <div class="captcha-container"></div>

2. Initialize the loginCaptcha and signupCaptcha components after the WebAuth constructor.

   var webAuth = new auth0.WebAuth(params);
   
   var loginCaptcha = webAuth.renderCaptcha(
       document.querySelector('.captcha-container'),
       null,
       (error, payload) => {
           if (payload) {
               triggerCaptcha = payload.triggerCaptcha;
           }
       }
   );
   
   var signupCaptcha = webAuth.renderSignupCaptcha(
       document.querySelector('.captcha-container'),
       null,
       (error, payload) => {
           if (payload) {
               triggerCaptcha = payload.triggerCaptcha;
           }
       }
   );

   Was this helpful?

   Yes /No

3. When you call the login method, assign the captcha property the value loginCaptcha.getValue():

   webAuth.login({
       realm: connection,
       username: username,
       password: password,
       captcha: loginCaptcha.getValue()
   }, function(err) {
       displayError(err);
       //...
   });

   Was this helpful?

   Yes /No
   To learn more about the login method’s callback function parameter (cb), read WebAuth on auth0.js documentation.

4. When you call the signupAndLogin method, assign the captcha property the value signupCaptcha.getValue():

   webAuth.redirect.signupAndLogin({
       connection: databaseConnection,
       email: email,
       password: password,
       captcha: signupCaptcha.getValue()
   }, function(err) {
       displayError(err);
       //...
   });

   Was this helpful?

   Yes /No
   To learn more about the signupAndLogin method’s callback function parameter (cb), read WebAuth on auth0.js documentation.

5. Reload the loginCaptcha and signupCaptcha components in your generic error handling logic.

   function displayError(err) {
     loginCaptcha.reload();
     signupCaptcha.reload();
   
     var errorMessage = document.getElementById('error-message');
     errorMessage.innerHTML = err.description;
     errorMessage.style.display = 'block';
   }

   Was this helpful?

   Yes /No

When you call the renderCaptcha and renderSignupCaptcha methods, you can configure the template for each supported CAPTCHA provider through the options parameter.

The templates property in the options parameter supports the following properties:

To learn more about the default template functions for each provider, read auth0.js/src/web-auth/captcha.js on GitHub.

If you'd like to support Bot Detection for passwordless flows, you must use version 9.24 or higher of the auth0.js library.

<script src="https://cdn.auth0.com/js/auth0/9.24/auth0.min.js"></script>

1. Add an element to render the CAPTCHA above the submit button. If you also support a username/password login, a separate element should be created for the passwordless CAPTCHA. For example: <div class="passwordless-captcha-container"></div>

2. Initialize the CAPTCHA component for passwordless flows after the WebAuth constructor.

   var passwordlessCaptcha = webAuth.renderPasswordlessCaptcha(
     document.querySelector('.passwordless-captcha-container')
   );

   Was this helpful?

   Yes /No

3. Add the captcha property to the Passwordless call, and reload the CAPTCHA component upon errors.

   webAuth.passwordlessStart({
     connection: 'email',
     send: 'code',
     email: 'foo@bar.com',
     captcha: passwordlessCaptcha.getValue()
   }, function (err,res) {
     if (err) {
       passwordlessCaptcha.reload();
       // handle errors
     }
     // continue
   });

   Was this helpful?

   Yes /No

• Add Bot Detection to Native Applications