How to configure CAPTCHA in Bitbucket Server

Still need help?

The Atlassian Community is here for you.

Ask the community

This article only applies to Atlassian's server products. Learn more about the differences between cloud and server.

Purpose

Bitbucket Server end users or Build systems need their CAPTCHA cleared often

This means that CAPTCHA verification is enabled and they probably have a script somewhere trying to clone repos with incorrect credentials. 

Randomly external tools (git clients: sourceTree, TortoiseGit) which try to access Repository on Bitbucket server get access denied - as Bitbucket is asking for CAPTCHA input. As I said this happens randomly - and it can be a big annoyance within our automatic build environment.

We recommend you pin down what is failing to login with the wrong username/password rather than disabling CAPTCHA for security reasons.

Disabling CAPTCHA can be achieved by following the guide below.

How can you identify which user is being blocked?

You can enable Audit logging on your instance

  • Audit logging in Bitbucket Server
  • Look for entries like the one below on BITBUCKET_HOME/log/audit:
    0:0:0:0:0:0:0:1 | AuthenticationFailureEvent | - | 1392111196025 | username | {"authentication-method":"form","error":"Invalid username or password."} | 633x670x0 | 1xzqso0

You can also use the following query on Bitbucket's database:


SELECT us.user_name
FROM cwd_user_attribute as atr
JOIN cwd_user as us ON atr.user_id=us.id
WHERE atr.attribute_name = 'failedAuthenticationAttemptCount' AND CAST(atr.attribute_value as integer) >= 5 ;


Common cause for CAPTCHA triggering users to be blocked:

Solution

How can I clear CAPTCHA for a specific user?

You can clear captcha for a Bitbucket Server user if you have "System Administrator" Global permissions assigned to you directly on the user's page.

How to disable CAPTCHA?

For security reasons, Bitbucket Server end users will be prompted for entering CAPTCHA after failing to login 5 times in a row.

You can disable CAPTCHA. However, we haven't surfaced this functionality in the Bitbucket Server admin UI as we think that it should be enabled by default and there are a few caveats when disabling it (e.g. risk of brute force attacks).

Disabling CAPTCHA will have the following ramifications:

  • Your users may lock themselves out of any underlying user directory service (LDAP, Active Directory etc) because Bitbucket Server will pass through all authentication requests (regardless of the number of previous failures) to the underlying directory service.
  • For Bitbucket Server installations where you use Bitbucket Server for user management or where you use a directory service with no limit on the number of failed logins before locking out users, you will open Bitbucket Server or the directory service up to brute-force password attacks.

In order to disable CAPTCHA as part of the authentication set the feature.auth.captcha property to false in your BITBUCKET_HOME/shared/bitbucket.properties for Bitbucket Server 3.2+ releases or  BITBUCKET_HOME/ bitbucket.properties if you are on a previous release.

You will have to create the bitbucket.properties file in the shared folder of your Bitbucket Server home directory if it doesn't already exist. Add the system property feature.auth.captcha=false.

The default value for it is true.

Bitbucket Server must be restarted after making this change for it to take affect.

What is the "CAPTCHA on Sign up" I see on the UI?


This CAPTCHA use case is completely different from the CAPTCHA on login as described above. Read on for more details.


You can find the screen bellow under Administration Cog Icon >> Authentication

This screen is related to the "Public Sign up" feature (whether to enable it or not) in Bitbucket Server. The "Public Sign Up" feature (when enabled) allows external users to create accounts on your Bitbucket Server instance through the login screen. Thus you might be able to make sure only humans are signing up to your public instance by enabling CAPTCHA. Notice that the CAPTCHA option can only be enable if you "Allow public sign up".

When you enable that feature, the following is added to your Bitbucket Server login screen:

The CAPTCHA option on the first image refers to enabling CAPTCHA during the "Public Sign up" process has nothing to do with the login CAPTCHA. See, for example, a sign up screen for an instance that's got it enabled:

Which conditions lead to the increase in the count of failed attempts?

  • Personal access tokens will NOT trigger captcha even with a repeated auth failures.

The CAPTCHA message is displayed on the next attempt to log-in after four incorrect ones. All of the following ways count towards the limit:

  • the log-in screen in the user interface
  • a git operation that requires authentication using the command line (e.g. a git push)
  • a REST API endpoint call


Note about AuthenticationFailureEvent and failedAuthenticationAttemptCount
As described in  BSERV-9904 - Getting issue details... STATUS , in certain conditions the AuthenticationFailureEvent will be logged twice in the audit log. However, this will not increase the failedAuthenticationAttemptCount on a single login attempt.


In other words, if the AuthenticationFailureEvent is logged only once and the clone URL did not contain a password, then the failedAuthenticationAttemptCount will not be increased. This means that users will not see Captcha messages earlier than the configured failed authentication count as a result of this. (I just validated that with the version 5.11.1 of Bitbucket).

The AuthenticationFailureEvent logged twice for the same user in a short timeframe would indicate that the authentication really failed.

What will the users see when the CAPTCHA threshold is reached?

The following will be displayed to the users when performing the next log-in:

  • the CAPTCHA screen when logging in via the user interface


  • the following message when performing a git operation from the command line

    fatal: remote error: CAPTCHA required
    Your Bitbucket account has been locked. To unlock it and log in again you must
    solve a CAPTCHA. This is typically caused by too many attempts to login with an
    incorrect password. The account lock prevents your SCM client from accessing
    Bitbucket and its mirrors until it is solved, even if you enter your password
    correctly.
    
    If you are currently logged in to Bitbucket via a browser you may need to
    logout and then log back in in order to solve the CAPTCHA.
    
    Visit Bitbucket at <Bitbucket_Server_url> for more details.
  • the following message when performing a REST API end point call

    {"errors":[{"context":null,"message":"Authentication failed. Please check your credentials and try again.","exceptionName":"com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException"}]}[root@localhost tmp]# <REST API end point command details>
    {"errors":[{"context":null,"message":"CAPTCHA required. Your Bitbucket account has been locked. To unlock it and log in again you must solve a CAPTCHA. This is typically caused by too many attempts to login with an incorrect password. The account lock prevents your SCM client from accessing Bitbucket and its mirrors until it is solved, even if you enter your password correctly.\n\nIf you are currently logged in to Bitbucket via a browser you may need to logout and then log back in in order to solve the CAPTCHA.\n\nVisit Bitbucket at <Bitbucket_Server_url> for more details.","exceptionName":"com.atlassian.bitbucket.auth.CaptchaRequiredAuthenticationException"}]} 

Following conditions may lead Bitbucket server to continuously ask for CAPTCHA

  • CAPTCHA will be reset only after a successful login. If the failed login count configured for Bitbucket server and AD/LDAP is same , user account may get locked in the AD/LDAP after the failed attempts and Bitbucket triggers CAPTCHA. This will never be cleared as user will never be able to login until the account get unlocked in AD/LDAP. This may be mistaken as Bitbucket server continuously asking CAPTCHA.  


Description

Bitbucket Server end users or Build systems need their CAPTCHA cleared often this means that CAPTCHA verification is enabled and they probably have a script somewhere trying to clone repos with incorrect credentials. 

Product Bitbucket
Platform Server
Last modified on Mar 19, 2019

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.