Client Web Fragment Plugin Modules

Rate this page:

HTTP Authentication 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 Handler plugin module provides a mechanism of authenticating users. The module has two responsibilities: authenticating users based on a HTTP request and validating that the current session is still valid. As an example, an SSO authentication module could authenticate a user based on a custom cookie. After the initial authentication succeeds, the SSO module should validate that the cookie is still provided on subsequent requests and may need to check with a remote server whether the SSO session is still valid.

All available authentication handlers are called in order of their configured weight (from low to high). See the HttpAuthenticationHandler interface for a complete description of how to implement a HttpAuthenticationHandler.

HTTP Authentication Handlers can optionally implement HttpLogoutHandler to receive a callback when a user logs out. HttpLogoutHandlers may manipulate the HTTP response on logout (e.g. redirect to an external login screen).


The root element for the HTTP Authentication Handler plugin module is <http-auth-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 Handler. This class must implement HttpAuthenticationHandler. The class may also implement HttpLogoutHandler to receive a callback on logout. N/A
captcha-supportWhether authentication failures should count against CAPTCHA limits.true
weightThe (integer) weight of the plugin module. Authentication handlers with a higher weight will be processed later.50

Built-in authentication handlers

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

Crowd SSO authentication handler20Disabled by default, can be enabled in
Embedded Crowd authentication handler100Authenticates based on username/password using the configured user directories. Opts out of authentication when no username is provided
Remember-me authentication handler110Authenticates using the remember-me cookie, if found. Opts out of authentication if no cookie is detected


Here is the atlassian-plugin.xml from an example container based authentication plugin, which defines a custom http-authentication-handler:


<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${}" plugins-version="2">
        <vendor name="${}" url="${project.organization.url}" />

    <component-import key="i18nService" interface="com.atlassian.bitbucket.i18n.I18nService"/>
    <component-import key="userService" interface="com.atlassian.bitbucket.user.UserService"/>

    <http-auth-handler key="containerAuthenticationHandler"


Rate this page: