Integrating ESOE with Confluence

Authors
Bradley Beddoes

Applicable versions (ESOE)
Beta 2

Applicable versions (Confluence)
2.4+

Overview

Confluence is a wiki and content management solution in use at many large education institutions today. We have worked with the Confluence API to integrate ESOE to handle all user authentication and where desired add an extra layer of authorization control (which can be much deeper then the current limitations of Confluence).

Installation

Confluence installation builds from a standard Java SPEP install. You should first be familiar with the document Java SPEP Installation Guide and comfortable with a generic SPEP install. For Confluence locations and steps vary slightly from a standard install so we'll follow the guidelines below.

This document assumes that $confleunce is the home directory of your confluence web application (and that its an extracted WAR per Atlassian install documentation) and that $tomcat is the home directory of your tomcat installation. Installation with Generic war files is fine if you wish to take that path.

The procedure for installing binaries is as follows (ensure permissions are set correctly for your tomcat and confluence users):

  1. Backup jar files in $tomcat/common/endorsed
  2. Extract spep-endorsed.tar.gz to $tomcat/common/endorsed
  3. Extract spep.tar.gz to a local working directory
  4. Create a directory called spep in your local working directory and extract the spep.war file inside this directory (this will look like the spep directory for a normal tomcat webapps deployment of spep.war)
  5. Copy the spep directory to the same parent directory that houses $confluence
  6. Create a core directory to store spep artifacts, a sub directory called config to store configuration and a sub directory called logging for log files. This must be readable by the user tomcat runs as. e.g /opt/spep/config and /opt/spep/logging
  7. Copy the spep.config file to the configuration directory e.g /opt/spep/config/spep.config
  8. At this point you have a choice in how to advise the SPEP install of your configuration location
    1. Java Property (RECOMMENDED). Export a java property called spep.data to your Java environment when tomcat starts. This should be set to the top level artifacts directory. e.g -Dspep.data=/opt/spep
    2. Create a Java properties file called spepvars.config and place it in $tomcat/webapps/spep/WEB-INF/ this is a standard java properties file format, set the variable spep.data to the same value you would above. We don't recommend this method though it may be useful in a multi spep environment, be sure to save your spepvars.config file safely, it will need to be copied back to the web application on each upgrade you perform.
  9. Edit the confluence.xml file in $tomcat/conf/Catalina/localhost adding crossContext="true" to the Context element for your Confluence installation.
  10. Create a file called spep.xml in $tomcat/conf/Catalina/localhost and enter the data:
    <Context path="/spep" docBase="<webappbasedir>/spep" debug="0" reloadable="true" crossContext="true">

    NB: The previous two steps can be implemented a number of ways depending on your deployment methods, the Context elements above may be solely listed in $tomcat/conf/server.xml or in the META-INF/context.xml files of each web application your deploying if your deploying WAR files.
  11. Extract the file spepfilter.tar.gz to your local working directory and copy the contained jar files to $confluence/WEB-INF/lib/
  12. Extract the file spepinteg-confluencejira.tar.gz to your local working directory and copy spepinteg-confluencejira.jar to $confluence/WEB-INF/lib
  13. Make the directory structure $confluence/WEB-INF/classes/com/qut/middleware/spep/integrators/atlassian/
  14. Copy the file integrator.properties to this location

SPEP Registration

Navigate to the "Register Service" page of the ESOE Manager.

Enter values for the following fields:

Field Description
Service name Human readable name for the service
Service URL Base URL or "home" of the service - the main entry point for a user agent e.g. https://confluence.company.com
Service Identifier Identifier of the service must be a URI, generally this is the same as the value entered above
Service description A description of what the service does
Service Authz Failure A message to be displayed by the central authorization failure page when access to one of your resources has been denied. This may contain HTML markup.

Click Next.

Add Service Contacts

Select the contact type from the list, and enter the other details for the contact.
When this is filled in, click "Save contact".

You may edit and delete contacts after they have been saved. After you have finished entering contacts, click Next.

Add Service Nodes

The "SPEPNode URL" is used as the base URL for the SPEP endpoints. If your running confluence on multiple nodes in a Layer 7 load balanced environment you will need to enter each of them here (you do not need a node for the service URL). The node domain names may be unrelated to the service domain if this is how your setup. e.g. https://confluence.company.com as a service address may have node URL's of https://somenode.company.com and https://someothernode.company.com

The different service locations here are paths to the service endpoints, using the SPEPNode URL as a base.

Select the server technology you are using. The default values for the endpoint paths will work for a default SPEP deployment. For confluence you need Java.

Click Save Node. You may add more nodes and edit or delete nodes that have already been added.

After you have finished entering nodes, click Next.

Finalize registration process

From this page you may check the information you have entered, and also navigate back to previous pages to make any alterations by clicking the Previous button.

Once you are happy with the configuration, click Complete.

Service configuration

Navigate to your service in the ESOE Manager application. Click on the "get service configuration" link. In the service description, click on the "service node configuration" link.

This page shows you the configuration values that need to be set up in the spep.config file, which can be found at the location you've earlier configured for spep.data.

For each of the configuration options shown by the ESOE Manager service node configuration page, enter the corresponding value for the current node in its spep.config file.

It is very important that each node's configuration be correct. There may be some differences between them.

Save the keystore file by clicking the "download keystore" link. The keystore will be the same for all nodes. Store the keystore as spep.data/config/spepKeystore.ks

Confluence configuration

Integrate with the core Confluence session handler

  1. Take a backup copy of $confluence/WEB-INF/classes/seraph-config.xml
  2. Edit the file $confluence/WEB-INF/classes/seraph-config.xml
  3. Replace the init-param entries at the top of the file with:
        <parameters>
            <init-param>
                <param-name>login.url</param-name>
                <param-value>/login?os_redirect=${originalurl}</param-value>
            </init-param>
            <init-param>
                <param-name>link.login.url</param-name>
                <param-value>/login?os_redirect=/dashboard.action</param-value>
            </init-param>
            <init-param>
                <param-name>cookie.encoding</param-name>
                <param-value>cNf</param-value>
            </init-param>
            <init-param>
                <param-name>login.cookie.key</param-name>
                <param-value>seraph.confluence</param-value>
            </init-param>
    
            <!--only basic authentication available-->
            <init-param>
                <param-name>authentication.type</param-name>
                <param-value>os_authType</param-value>
            </init-param>
        </parameters>
    
  4. Find the <authenticator> element and replace the class value with "com.qut.middleware.spep.integrators.atlassian.ConfluenceJiraIntegrator"
  5. Take a backup copy of $confluence/WEB-INF/web.xml
  6. Edit the file $confluence/WEB-INF/web.xml
  7. Add the following filters above the filter of 'johnson':
        <filter>
            <filter-name>spep-filter</filter-name>
            <filter-class>com.qut.middleware.spep.filter.SPEPFilter</filter-class>
    
            <init-param>
                    <param-name>spep-context</param-name>
                    <param-value>/spep</param-value>
            </init-param>
       </filter>
    
       <filter>
            <filter-name>spep-redirect</filter-name>
            <filter-class>com.qut.middleware.spep.integrators.atlassian.LoginRedirectFilter</filter-class>
       </filter>
    
  8. Add the following filter mappings above the filter mapping for 'login'
        <filter-mapping>
            <filter-name>spep-filter</filter-name>
            <url-pattern>/*</url-pattern>
        </filter-mapping>
    
        <filter-mapping>
            <filter-name>spep-redirect</filter-name>
            <url-pattern>/*</url-pattern>
        </filter-mapping>
    
  9. Edit the file $confluence/WEB-INF/classes/com/qut/middleware/spep/integrators/atlassian/integrator.properties and set values for each field, the defaults may suffice but speack to your ESOE system administrator to ensure they match your sites attribute release policy.

Logging configuration

We recommend (but it is not essential) you configure a log4j.xml file at $tomcat/shared/classes as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" debug="true">
        <logger name="com.qut.middleware.spep">
                <level value="DEBUG" />
                <appender-ref ref="spep-logger" />
        </logger>

        <logger name="spep.authn">
                <level value="DEBUG" />
                <appender-ref ref="spep-authn-logger" />
        </logger>

        <logger name="spep.authz">
                <level value="DEBUG" />
                <appender-ref ref="spep-authz-logger" />
        </logger>

        <appender name="spep-logger" class="org.apache.log4j.FileAppender">
                <param name="Append" value="false" />
                <param name="File" value="$spep.data/logging/spep.log" />
                <layout class="org.apache.log4j.PatternLayout">
                        <param name="ConversionPattern" value="%d %-5p %c - %m%n" />
                </layout>
        </appender>

        <appender name="spep-authn-logger" class="org.apache.log4j.FileAppender">
                <param name="Append" value="false" />
                <param name="File" value="$spep.data/logging/spep-authn.log" />
                <layout class="org.apache.log4j.PatternLayout">
                        <param name="ConversionPattern" value="%d %-5p %c - %m%n" />
                </layout>
        </appender>

        <appender name="spep-authz-logger" class="org.apache.log4j.FileAppender">
                <param name="Append" value="false" />
                <param name="File" value="$spep.data/logging/spep-authz.log" />
                <layout class="org.apache.log4j.PatternLayout">
                        <param name="ConversionPattern" value="%d %-5p %c - %m%n" />
                </layout>
        </appender>

</log4j:configuration>

NB: You should replace $spep.data with the directory your storing spep artifacts in.

Deploy changes and restart Confluence

The last step is simply to restart the Confluence tomcat instance. You should watch the log files configured above for any problems on startup then access your confluence repository. Don't forget to enable your service in ESOE Manager and ensure you have an authorization policy giving you access (everyone is denied access to new services by default).

Feedback

We aim to continually improve this documentation set to make it as easy as possible for new users and seasoned users alike to setup Confluence integration. We welcome any comments or additions you may have on the ESOE users mailing list at any time.

Also available in: HTML TXT