HTTP Authentication Handler Plugin Module

Introduction

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).

Configuration

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

Attributes

Name Required Description Default
key The identifier of the plugin module. This key must be unique within the plugin where it is defined. N/A
class 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-support Whether authentication failures should count against CAPTCHA limits. true
weight The (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:

Name Weight Description
Crowd SSO authentication handler 20 Disabled by default, can be enabled in bitbucket.properties
Embedded Crowd authentication handler 100 Authenticates based on username/password using the configured user directories. Opts out of authentication when no username is provided
Remember-me authentication handler 110 Authenticates using the remember-me cookie, if found. Opts out of authentication if no cookie is detected

Example

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


<atlassian-plugin key="com.atlassian.bitbucket.server.bitbucket-docs" name="Bitbucket Server - Documentation" plugins-version="2">
    <plugin-info>
        <description>Base POM for Atlassian projects</description>
        <version>4.7.1</version>
        <vendor name="Atlassian" url="http://www.atlassian.com" />
    </plugin-info>

    <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"
                       class="com.atlassian.bitbucket.auth.container.RemoteUserAuthenticationHandler"
                       captcha-support="false"
                       weight="100"/>

</atlassian-plugin>