Client Web Fragment Plugin Modules

HTTP Authentication Failure Handler Plugin Module


Bitbucket Server 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:


keyYesThe identifier of the plugin module. This key must be unique within the plugin where it is defined.N/A
classYes The fully qualified Java class name of the HTTP Authentication Failure Handler. This class must implement HttpAuthenticationFailureHandler. N/A
weightThe (integer) weight of the plugin module. Authentication failure handlers with a higher weight will be processed later.50

Built-in authentication failure handlers

Bitbucket Server 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 Server Authentication plugin">

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

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


Rate this page: