HTTP Authentication Handler Plugin Module

Introduction

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 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	Yes	The identifier of the plugin module. This key must be unique within the plugin where it is defined.	N/A
class	Yes	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 Data Center 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:

1
2

<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.name}" plugins-version="2">
    <plugin-info>
        <description>${project.description}</description>
        <version>${project.version}</version>
        <vendor name="${project.organization.name}" url="${project.organization.url}" />
    </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>