HTTP authentication with Seraph

Introduction

This document describes how the default security system in Confluence works, using the Seraph library for HTTP authentication.

Extending the security system by subclassing Seraph's authenticator and configuring the seraph-config.xml file is outside the scope of this document. Single Sign-on Integration with the Atlassian stack explains one way to integrate Seraph with Atlassian products.

Flowchart diagrams

The easiest way to understand Confluence's authentication process is with the following diagrams.

Authentication flowchart

Because the Authenticator.login(request, response, username, password, rememberMe) method occurs three times, and is slightly complex, it has been broken into its own sub-flowchart.

flowchart showing the login method

By default, Confluence allows any attempt with the correct username and password login form attributes through to all action endpoints (for example <base_url>/dashboard.action). For security purposes, if you wish to restrict this behavior you can enable the rejection of these calls. To reject calls to all but a list of specific endpoints, you can provide an allowlist for the login flow.

1
2
<init-param>
    <param-name>login.submit.url</param-name>
    <param-value>/dologin.action</param-value>
</init-param>

In Confluence 7.13.20 and later, your seraph-config.xml will have the following allowlist parameters by default:

1
2
<init-param>
    <param-name>login.submit.url</param-name>
    <param-value>/dologin.action</param-value>
</init-param>

If you wish to add more paths to the login flow, modify the parameters within the XML file and add more paths using comma separation as shown in this example:

1
2
<init-param>
    <param-name>login.submit.url</param-name>
    <param-value>/a.action,/b.action,/c.action</param-value>
</init-param>

Supported authentication methods

The default Seraph authenticator supports four methods of authentication, as shown in the flowchart:

request parameters: os_username and os_password (sent as login POST body)
URL query parameters: os_username and os_password (removed in Confluence 7.10)
session attribute storing the logged-in user
cookie storing username and password ('remember me' login)
HTTP basic authentication via standard headers

Each method is tried in the order above. A successful login at an earlier method continues without checking the later methods. Failure at one method means continuing with the later methods until all are exhausted. At this point, the user is considered an anonymous user, and treated according to the permissions of an anonymous user in Confluence.

Looking through the source code will show that Seraph supports role-based authentication, but this is only used in Confluence for the /admin/ URL restriction.

Starting from Confluence 7.10, you can no longer use URL query parameters to log in. However, if you need quick login for automated tests, you can add the following system property:

atlassian.allow.insecure.url.parameter.login=true

This will allow you to use os_username, os_password, and os_destination request parameters.

In Confluence 9.1, a new login page that supports two-step verification has been added. This uses the 2SV REST API to log in to users. To revert back to the Seraph-base login page, add the following system property: atlassian.authentication.legacy.mode=true.

Confluence Internals