This documentation relates to SharePoint Connector 1.9
If you are using an earlier version, please view the previous versions of the SharePoint Connector documentation and select the relevant version.

Skip to end of metadata
Go to start of metadata

This page is part of the installation guide for the Confluence SharePoint Connector. It tells you how to configure access to Confluence using Integrated Windows Authentication via IIS. These instructions apply to the connector for SharePoint 2007.

On this page:

Overview

In this configuration, both SharePoint and client browsers are authenticated against Confluence using Windows authentication provided by a Microsoft Internet Information Services (IIS) server. IIS proxies the pre-authenticated requests through to Confluence and then returns the content to the requester. Confluence and IIS communicate using Apache JServ Protocol (AJP).

Use this Configuration when...
  • You want to enable 'pass-through authentication' for your users logged in to a Windows domain.
  • All users who access Confluence are members of an Active Directory domain.
  • Confluence is running on Windows Server, or you are able to set up Windows Server to act as a proxy for Confluence.

If you have not already seen our guide to planning your environment, you can refer to it for information that will help you select the best configuration for your environment.

Caveats

Supported Platforms

Due to the complex nature of this configuration, Atlassian is only able to provide support if your configuration satisfies these additional conditions:

  • Confluence must be installed as a stand-alone Tomcat application server.
  • The only supported operating systems for this configuration are Windows Server 2003, Windows Server 2008 and Windows Server 2012.
  • The server must be a member of the same Active Directory domain that contains the user records that will be authenticated.
  • Confluence must be configured to use LDAP integration to Active Directory for user management.

Additional Dependencies

Using this configuration adds a number of additional dependencies to Confluence, which you should review.

Custom Seraph Authenticator

This configuration requires the use of a specialised Seraph authenticator for Confluence. Install and configure this component on the server that host Confluence. If you are already using a different custom Seraph authenticator, you may not be able to use this configuration. In this situation, you must either choose a different configuration for the SharePoint Connector or consider developing a new custom Seraph authenticator that aggregates the functionality of both.

No support for custom authenticators

Please note that we are unable to provide support for any custom authenticators not written or explicitly supported by Atlassian.

Custom ISAPI Filter

This configuration requires the use of a custom ISAPI filter for IIS that can communicate using AJP. Install and configure this component on the server that has IIS installed. Atlassian will only support the use of the open source Tomcat Connector provided by the Apache Tomcat project.

Limited support for third-party software

Please note that Atlassian is unable to provide in-depth support for problems encountered with the Tomcat Connector, as this software is written and maintained by the Apache Software Foundation. Atlassian will assist with ensuring the correct configuration values are applied and capturing diagnostic information, but any issues encountered with the Tomcat Connector must be raised through the appropriate channels with the Apache Tomcat project or with another organisation that provides commercial support for Tomcat.

Anonymous Access Disabled

Due to limitations with the custom Seraph authenticator that Confluence requires for this configuration, it is not possible to set up anonymous access for Confluence when using this configuration.

Atlassian is currently reviewing the suitability of using the third-party NTLM Authenticator for Confluence instead.

Known issues

These are some reported problems with this configuration:

  • The user is not able to explicitly log out. Even when they select the logout action, they remain logged-in.
  • If you log in using NTLM authentication as a user that does not exist in the AD repository, you will not see the personal menu in Confluence's top navigation bar.
  • You cannot fall back to using forms-based authentication or anonymous authentication.

Assumptions

  • This instruction assume that you install and configure Confluence, Tomcat and IIS on the same server.
  • It's possible that you install Tomcat and Confluence on one server and IIS on the different server. The steps are quite similar, there will be a notice at certain steps if the configuration is applicable for more than one server configuration approach.

Installation Instructions

Step 1. Configure Confluence for LDAP User Management

If you have already configured Confluence to connect to your Active Directory domain, then skip ahead to the next step.

Set up your Confluence server to synchronise its user repository with your Windows Active Directory domain. See the Confluence documentation on LDAP user management.

Step 2. Configure IIS

This and following steps guide you through the configuration required to use IIS as an NTLM authenticator for Confluence. NTLM is an authentication format developed by Microsoft. While some third-party implementations are available, IIS provides the most robust and full-featured NTLM authentication support.

Summary of this configuration:

  • It places the Tomcat application server running Confluence behind an IIS website configured for Integrated Windows Authentication.
  • IIS is then configured with a custom ISAPI handler that communicates directly with the Tomcat server using Apache JServ Protocol to serve the Confluence content back to the user.

Please follow the guide below that matches the version of your Windows Server:

Step 3. Configure Confluence for Integrated Windows Authentication

This section of the guide describes the steps necessary to configure Confluence to co-operate with the IIS Web Server.

Throughout this section, '%confluence_install%' refers to your Confluence installation directory .

Step 3.1: Set Confluence Path

This step is only necessary if your IIS instance is already hosting other websites and you want to host Confluence underneath an existing site (for example, if your corporate intranet is hosted at http://intranet.company.com and you want to host Confluence at http://intranet.company.com/confluence).

  1. Edit the %confluence_install%\conf\server.xml file.
  2. Find the Context element in the file, and then change the path value to '/confluence'.
    The line should look something like this:

  3. Save your changes and close the file.
  4. Restart Confluence and verify that it is now accessible from the new path, such as http://localhost:8080/confluence.

Step 3.2: Add AJP Connector

Now you will change Tomcat's configuration, replacing the standard Coyote HTTP connector (which allows Tomcat to send and receive HTTP traffic) with a custom AJP connector (which allows Tomcat to communicate using Apache JServ Protocol).

  1. Edit the %confluence_install%\conf\server.xml file.
  2. Locate the Connector element and comment it out entirely.
  3. Add a new Connector element that looks like the one below. The values that must match exactly are address, protocol and tomcatAuthentication:

    If IIS is not located on the same server as Confluence, then the key value pair address should be omitted.

    <Connector port="8009" enableLookups="false" redirectPort="8443" protocol="AJP/1.3" 
    tomcatAuthentication="false" URIEncoding="UTF-8" />
  4. Ensure that your server.xml file now contains only a single Connector definition. You still have the option to have more than one Connector elements definition but in this configuration we recommended that only one Connector element definition is used.
  5. Save your changes and close the file.
  6. Restart Confluence and ensure that the server initialises successfully.

Step 3.3: Add Custom Authenticator


By default, Confluence will not understand the pre-authenticated requests that come through via a Single Sign-On solution (such as Jespa or an IIS proxy). In order to allow this authentication information to pass through, you must modify the authenticator module used by Confluence.
  1. Download the latest SharePoint Connector custom authenticator appropriate for your version of Confluence (see the below table):

    Confluence 4.3.x and earlierConfluence 5.0.x to 5.4.xConfluence 5.5 and later
    customauth-0.6.jarcustomauth-1.0.jarcustomauth-1.1.jar
  2. Copy the downloaded 'customauth-x.x.jar' to your %confluence_install%\confluence\WEB-INF\lib directory.
  3. Edit the %confluence_install%\WEB-INF\classes\seraph-config.xml file.
  4. Locate the Authenticator element and replace it with the following (you may wish to backup the file in case you wish to revert to the original configuration):

  5. Save your changes and close the file.
  6. Restart Confluence and ensure that the server initialises successfully.

Step 3.4: Modify Base URL

The final step in configuring Confluence is to modify the Server Base URL to point to the IIS web site, rather than directly to Confluence. This ensures that any hyperlinks generated within Confluence pages will direct users through the IIS website. For example, if your Tomcat server runs Confluence on http://intranet.company.com:8080/confluence and the IIS web site runs on http://intranet.company.com, then the Confluence Base URL needs to be changed to http://intranet.company.com/confluence.

See the Confluence documentation for instructions on modifying the Base URL.

Step 4. Set Client Browser Options

In order for users to be automatically logged in to Confluence without being prompted for their username and password, the browser must be correctly configured for pass-through authentication.

Please instruct all users to ensure that the recommended browser settings are applied.

Next Step

To continue with the installation of the SharePoint Connector, please install and configure the SharePoint feature.

  • No labels

4 Comments

  1. the custom authenticator used to put new users into the confluence-users group when they logged in.  It doesn't appear to be doing that anymore.  Has anything changed?

    1. Hi Laurie,

      In Confluence 3.4 and earlier, the SharePoint Connector custom authenticator did not support adding new users automatically to the confluence-users group (this functionality was supported by a different Confluence authenticator and we couldn't merge the two of them together).

      In Confluence 3.5 and onwards, the new embedded LDAP management in Confluence allows default group memberships to be configured directly against the directory by an administrator - you'll need to set this up against your LDAP directory  by following the instructions in this guide: Connecting to an LDAP Directory - Adding Users to Groups Automatically

       

      1. I tried this by adding confluence-users to the autoaddgroups.  It seemed to have worked yesterday in my staging environment but now it doesn't work in production or staging.

        1. Hi Laurie,

          Check what version of the customauth jar you have in your Confluence server's WEB-INF/lib folder.  You'll need to be using the latest version (customauth-0.6.jar).