Support for Server products ended Feb. 15, 2024. Learn what this means for you.

HTTP Authentication Success 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

HTTP Authentication Success Handler plugin modules receive a callback on authentication success and can customize the HTTP response, usually by redirecting to a custom page. The built-in authentication success handler redirects the user back to the URL they requested prior to being sent to the login screen, or to the projects list if they requested the login screen explicitly.

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

Configuration

The root element for the HTTP Authentication Success Handler plugin module is <http-auth-success-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 Success Handler. This class must implement `HttpAuthenticationSuccessHandler`.	N/A
weight		The (integer) weight of the plugin module. Authentication success handlers with a higher weight will be processed later.	50

Built-in authentication success handlers

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

Name	Weight	Description
Crowd SSO authentication success handler	20	When SSO integration has been enabled this starts an SSO session even if another authenticator authenticated the user
Session creating success handler	50	Creates an HttpSession if it does not exist yet, except for requests authenticated using BASIC authentication
Redirecting success handler	100	Redirects the user to the URL provided in the `next` request parameter field or the projects page if none was provided

Example

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

    <plugin-info>
        <description>Configuration example</description>
        <version>1.0</version>
        <vendor name="Atlassian" url="http://www.atlassian.com"/>
    </plugin-info>

    <http-auth-success-handler key="customSuccessHandler"
                               class="com.your.domain.custom.auth.CustomAuthenticationSuccessHandler"
                               weight="90"/>

</atlassian-plugin>