Client Web Fragment Plugin Modules

HTTP Authentication Failure Handler Plugin Module


Bitbucket Data Center allows plugins to participate in the authentication chain through three plugin module types.

  • http-authentication-handler - used to authenticate users and validate whether the current authentication session is still valid.
  • http-authentication-success-handler - called when a user is authenticated successfully using any of the installed http-authentication-handler modules.
  • http-authentication-failure-handler - called when authentication using any of the installed http-authentication-handler modules failed.

Purpose of this Module Type

A HTTP Authentication Failure Handler plugin module can customize the behavior on authentication failure. All available failure handlers are called in order of their configured weight (from low to high). See the HttpAuthenticationFailureHandler interface for a complete description of how to implement a HttpAuthenticationFailureHandler. The built-in handlers do the following:

  • For REST requests, return a HTTP 401 authentication challenge with the authentication error message as a JSON payload.
  • For SCM (git) requests, write out the authentication error message to the remote client.
  • For BASIC authentication, send a HTTP 401 authentication challenge.
  • For all other cases redirect to the login page.

In a typical SSO scenario, the HTTP Authentication Failure Handler module can be used to redirect the user to an external login page.


The root element for the HTTP Authentication Failure Handler plugin module is <http-auth-failure-handler/>. It allows the following configuration attributes:


Built-in authentication failure handlers

Bitbucket Data Center bundles a number of authentication failure handlers. When choosing the weight of your authentication failure handler, consider whether your http-authentication-failure-handler should be applied before or after the built-in handlers:

REST failure handler60Writes authentication error messages in JSON format and sends a HTTP 401 WWW-Authenticate response
SCM authentication failure handler80Writes authentication error messages to the SCM client using the SCM HTTP protocol for hosting commands
Basic auth challenge failure handler90If the request was authenticated using BASIC auth, this handler sends a HTTP 401 WWW-Authenticate response
Redirecting failure handler100Redirects the user to the login page


<atlassian-plugin key="com.your.domain.custom.auth" name="Bitbucket Data Center Authentication plugin">

        <description>Configuration example</description>
        <vendor name="Atlassian" url=""/>

    <http-auth-failure-handler key="customFailureHandler"


Rate this page: