Understanding User Management in Confluence

Looking for help with your user management configuration? See Requesting External User Management Support.

Try Atlassian Crowd for powerful user administration

Atlassian's Crowd is a web-based single sign-on (SSO) tool that simplifies application provisioning and identity management, including LDAP integration. For more information, please see the Crowd documentation on Integrating Crowd with Confluence.

On this page:

Components of User Management

Authentication - determining what user identity is making a request to Confluence.
User management - storing and retrieving core information about users.
Group membership - storing and retrieving groups, and group membership.
Profile information - providing metadata associated with users.

It's important to understand that these are separate components of the user management system. The term LDAP integration is not really meaningful, because you could use LDAP repository for any or all of the above tasks.

For example, in OSUser authentication can be performed against different repository to that used for group membership queries. In AtlassianUser, authentication and group membership can be retrieved from LDAP, but profile information is still stored in the Confluence database.

Authentication

Seraph

Almost all authentication in Confluence (and JIRA) is performed through Seraph, Atlassian's open source web authentication framework. The goal of seraph is to provide a simple, extensible authentication system that we can use on any application server.

Seraph is implemented as a servlet filter. Its sole job is, given a web request, to associate that request with a particular user (or no user if the request is anonymous). It supports several methods of authentication, including HTTP Basic Authentication, form-based authentication, and looking up credentials already stored in the user's session.

Seraph performs no user management itself. It merely checks the credentials of the incoming request, and delegates any user-management functions (looking up a user, checking a user's password is correct) to Confluence's user-management subsystem.

If you were looking to integrate Confluence with a Single Sign-On (SSO) infrastructure, you would do so by writing a custom Seraph authenticator (and in fact, many customers have done so).

XML-RPC and SOAP Authentication

Normally, requests for Confluence's remote API will include an authentication token as the first argument. With this method of authentication, XML-RPC and SOAP authentication requests are checked directly against the user-management framework, and tokens are assigned directly by the remote API subsystem. These requests do not pass through Seraph authenticators.

However, if the provided token argument is blank, Seraph will be used as a fallback authentication method for remote API requests. So, to use a custom Seraph authenticator with XML-RPC or SOAP requests, ensure that you pass an empty string as the authentication token to remote API methods.

Password Authentication and User Management

By default, password authentication is delegated from Seraph to the user management system. This is not necessary, however. Single Sign-On systems may have no password authentication at all, and get all the necessary credentials from the SSO provider.

Confluence User Management Frameworks

The rest of this document covers the user management frameworks used by Confluence: AtlassianUser and OSUser.

AtlassianUser

AtlassianUser is a new user and group management framework developed by Atlassian, and is the core framework used in Confluence since version 2.1. AtlassianUser was developed with the following goals in mind:

Support LDAP as a fully functional repository for authentication, group management and profile information (profile information not yet implemented).
Compatibility with both JIRA and Confluence (JIRA support not yet implemented).
Be simple to configure.

AtlassianUser provides user, group and profile management services to Confluence. It does so by delegating tasks to configurable repositories. Multiple repositories can be configured, so for example Confluence can draw user information from both the database and an LDAP server.

Default Configuration

Configuration of AtlassianUser is done through the <<confluence-install>>\confluence\WEB-INF\classes\atlassian-user.xml file. See the atlassian-user.xml reference page. (In Confluence 2.1, configuration of AtlassianUser is done through the atlassianUserContext.xml file. )

For Confluence 2.7.0 and later:

All user management is performed by AtlassianUser's native providers.
OSUser delegation is still supported for customers who rely on the OSUser/JIRA bridge or the old-style OSUser LDAP support.
Refer to the Confluence 2.7 Upgrade Guide for details of the automatic migration which may occur during the upgrade process, for customers who are using the standard user management framework.

For Confluence 2.6.x and earlier:

Confluence's AtlassianUser configuration delegates all user, group, profile and password authentication to OSUser.

Database (Hibernate) Support in AtlassianUser

AtlassianUser can store user, group and profile data directly in Confluence's database. This is the default behaviour for Confluence 2.7.0 and later.

LDAP Support in AtlassianUser

AtlassianUser currently supports password authentication, user management and group management with an LDAP server. Follow the instructions on configuring AtlassianUser LDAP integration.

At this point, only read-only access to LDAP is planned. Java's JNDI-LDAP interface does not support updating an LDAP repository, and the administration tools that come with LDAP servers such as Microsoft Active Directory are generally comprehensive and already available in enterprise IT departments.

JIRA Integration via AtlassianUser

AtlassianUser will not support delegating Confluence user management to JIRA. Instead, our goal is to implement AtlassianUser as the JIRA user management framework as well. Once this is done, both Confluence and JIRA can use the same LDAP server for their authentication and group management.

OSUser

OpenSymphony User was Confluence's core user management framework until it was replaced by AtlassianUser in version 2.1. OSUser is still supported through AtlassianUser's OSUser repositories. OSUser is also built around the model of pluggable providers, but its LDAP support is limited.

OSUser Database (Hibernate) Providers

In its default configuration, Confluence's OSUser providers store a list of users and groups together with profile information in tables in the Confluence database:

os_user (authentication)
os_group (group membership)
os_user_group (group membership)
os_propertyentry (profile information)

The hashed password in the os_user table is used to authenticate the user unless LDAP support is enabled. The os_user_group table is queried for group membership information.

OSUser configuration is controlled through the <<confluence-install>>\confluence\WEB-INF\classes\osuser.xml file.

LDAP Support in OSUser

OSUser only supports authentication against an LDAP server. That is, you can check user passwords against LDAP, but all other user information must be shadowed in the Confluence database. Follow the instructions on configuring OSUser LDAP authentication.

If you need support for LDAP user information or group membership as well, you should use AtlassianUser instead (see above).

Delegating User Management to JIRA via OSUser

Confluence can use OSUser to retrieve information for authentication, group membership and profile information from JIRA.

If you look at the discussion of OSUser's implementation above, you can see how this can works pretty easily. A data source to JIRA database is configured in Confluence which lets Confluence read directly from JIRA's os_* tables. For example, when a user is created in JIRA, the username and password goes in the os_user table in the JIRA database. Confluence looks at the same table in the JIRA database to authenticate the user.

Access to the JIRA database is read-only. For this reason, Confluence maintains a subset of the user's profile information locally in the Confluence database (things like last login time and user preferences that Confluence needs to be able to modify) .

Follow the instructions on configuring OSUser delegation to JIRA.

Page tree