Delegate user management to use JIRA logins

If you already have a significant user base set up inside JIRA, it makes sense to connect Confluence up to it so user management is centralised and not duplicated. This document outlines how to delegate Confluence's user authentication and group management to JIRA so that you can use your JIRA users to login to Confluence.

Read Before Proceeding

1. The examples used in this document are based on Tomcat Application Server and the MySQL database, but the same concepts (but not the verbatim examples) can be applied to other application servers or databases.
   
   
2. Always install Confluence with a new database. Do not attempt to use the existing Jira database, with either JDBC or data source. Do not add any spaces or content once Confluence installation is complete. Users in Confluence will no longer be valid once you switch over to using your JIRA users
   
   
3. If JIRA is using LDAP for authentication, you should not use JIRA for Confluence user management. Use Add LDAP Integration instead
   
   
4. If you have existing users or groups in Confluence, these users will not be available once you switch to using JIRA's user management. Any existing content will no longer be associated with valid users
   
   
5. If you run into a problem, check the Troubleshooting section

Technical Overview

In the configuration described below, Confluence will use JIRA's database for its user and group information. The Confluence application will have two database connections:

1. A connection to the primary database, set up during Confluence installation. This database stores all the normal Confluence data: spaces, pages, comments, etc.
2. A read-only data source connection to JIRA's database, set up after Confluence is installed. Confluence reads information about users and groups from this database.

The reason this works is because both JIRA and Confluence use the same user management library, OSUser. The OSUser database schema is the same in JIRA and Confluence, so Confluence can easily read from JIRA's tables to get the user and group information.

Step One: Installing Confluence

Skip this step if you have installed Confluence already and completed the setup wizard.

1. If you are running JIRA standalone please follow these instructions for installing Confluence.

2. If you have JIRA deployed under your own tomcat server, please follow these instructions.

3. Ensure that Confluence is running and has been set up, that is, you have completed the setup wizard and verified that you can create pages.

4. Shutdown Confluence.

Step Two: Setting up datasource to JIRA's database

To enable Confluence to delegate all user authentication attempts and group membership queries to JIRA, it needs to made of aware of JIRA's database (and hence the user tables in JIRA's database).

In Tomcat this is achieved by specifying JIRA's database as a resource. You will need to declare it inside the <context> descriptor you set up in Step One.

If you are running Confluence stand-alone (or Confluence inside a JIRA stand-alone) and aren't sure which version of Tomcat you are using, check your log files. You'll see *INFO: Starting Servlet Engine: Apache Tomcat/5.5.nn* if you are using Tomcat 5.5.

• Tomcat 4.x and Tomcat 5.0.x: Sample context descriptor

  <Context path="/confluence" docBase="C:/programs/confluence" swallowOutput="true">
      <Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"/>
      <ResourceParams name="jdbc/JiraDS">
      <parameter>
      <name>username</name>
          <value>your_db_username</value>
      </parameter>
      <parameter>
      <name>password</name>
          <value>your_db_password</value>
      </parameter>
      <parameter>
      <name>driverClassName</name>
          <value>com.mysql.jdbc.Driver</value>
      </parameter>
      <parameter>
      <name>url</name>
          <value>jdbc:mysql://your.domain.com/jira_database_name?autoReconnect=true</value>
      </parameter>
      <parameter>
          <name>factory</name>
          <value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
      </parameter>
      </ResourceParams>
  </Context>
  

  
  
• Tomcat 5.5.x: This version of Tomcat has a new syntax for specifying resources (note that you don't add a new context to server.xml, just add the Resource to your existing Context):

  <Context path="/confluence" docBase="C:/programs/confluence" swallowOutput="true">
    <Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"
       username="your_db_username"
       password="your_db_password"
       driverClassName="com.mysql.jdbc.Driver"
       url="jdbc:mysql://your.domain.com/jira_database_name?autoReconnect=true"/>
  </Context>
  

Step Three: Installing the JDBC driver

Ensure that your JDBC driver is on the classpath of your application server. In this example, a jar for the mysql driver should be in the /common/lib folder.

1. Download the mysql driver from here.
   
   
2. Copy the jar file into the /common/lib folder

Step Four: Modify osuser.xml

1. Find the osuser.xml file in the /confluence/WEB-INF/classes folder and open in a text editor. Comment out the following block of code:

   <provider class="bucket.user.providers.CachingCredentialsProvider">
           <property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateCredentialsProvider</property>
           <property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property>
       </provider>
       <provider class="bucket.user.providers.CachingAccessProvider">
           <property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateAccessProvider</property>
           <property name="chain.configuration.provider.class">bucketuser.BucketHibernateConfigProvider</property>
       </provider>
       <provider class="bucket.user.providers.CachingProfileProvider">
           <property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateProfileProvider</property>
           <property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property>
       </provider>
   

   
   
   
2. Uncomment this block:

   <provider class="bucket.user.providers.CachingCredentialsProvider">
           <property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcCredentialsProvider</property>
           <property name="chain.datasource">java:comp/env/jdbc/JiraDS</property>
       </provider>
       <provider class="bucket.user.providers.CachingAccessProvider">
           <property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcAccessProvider</property>
           <property name="chain.datasource">java:comp/env/jdbc/JiraDS</property>
       </provider>
       <provider class="bucket.user.providers.CachingProfileProvider">
           <property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcProfileProvider</property>
           <property name="chain.datasource">java:comp/env/jdbc/JiraDS</property>
           <property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property>
       </provider>
   

   
   
   Your osuser.xml should now look like this:

   <opensymphony-user>
       <!--
   		Authenticators can take properties just like providers.
   
   		This smart authenticator should work for 'most' cases - it dynamically looks up
   		the most appropriate authenticator for the current server.
   	-->
       <authenticator class="com.opensymphony.user.authenticator.SmartAuthenticator"/>
   
       <!-- JIRA User management (with caching) -->
       <!-- Note: Do not add any line breaks or spaces when specifying the chain.classname, otherwise a ClassNotFoundException will be thrown -->
   
       <provider class="bucket.user.providers.CachingCredentialsProvider">
           <property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcCredentialsProvider</property>
           <property name="chain.datasource">java:comp/env/jdbc/JiraDS</property>
       </provider>
       <provider class="bucket.user.providers.CachingAccessProvider">
           <property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcAccessProvider</property>
           <property name="chain.datasource">java:comp/env/jdbc/JiraDS</property>
       </provider>
       <provider class="bucket.user.providers.CachingProfileProvider">
           <property name="chain.classname">com.atlassian.confluence.user.providers.jira.JiraJdbcProfileProvider</property>
           <property name="chain.datasource">java:comp/env/jdbc/JiraDS</property>
           <property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property>
       </provider>
       
       <!--
       <provider class="bucket.user.providers.CachingCredentialsProvider">
           <property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateCredentialsProvider</property>
           <property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property>
       </provider>
       <provider class="bucket.user.providers.CachingAccessProvider">
           <property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateAccessProvider</property>
           <property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property>
       </provider>
       <provider class="bucket.user.providers.CachingProfileProvider">
           <property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateProfileProvider</property>
           <property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property>
       </provider>
       -->
   
       <!--<provider class="com.opensymphony.user.provider.memory.MemoryCredentialsProvider" />
       <provider class="com.opensymphony.user.provider.memory.MemoryAccessProvider" />
       <provider class="com.opensymphony.user.provider.memory.MemoryProfileProvider" />-->
   </opensymphony-user>
   

   Please make sure your file looks like this.

In this example, JiraDS is the name of the JIRA datasource you are sharing with Confluence. If you have changed the name in step 2 of this documentation, you will need change all occurences of the value here too.

You can also download the already configured file here.

Step Five: Customize osuser.xml

In some cases you may need to customize the behavior of the JiraJdbc classes, you can do this by setting properties within the osuser.xml file.

This process is documented here.

Step Six: Creating Confluence Groups in JIRA

1. Add confluence-users and confluence-administrators groups in JIRA
   
   
2. Add yourself to both these groups.
   
   
   • To give your existing JIRA users access to Confluence, you have two options.
   • Manually edit the groups of these users inside JIRA and give them membership to one or both of these confluence groups OR
   • Startup Confluence. Log in using your JIRA account, and go to Administration and then Global Permissions. Now add USE permission to your desired JIRA groups.

Step Seven: Activating External User Management

Since user management is now conducted in JIRA and outside of Confluence, you will need to switch external user management on.

NOTE: Activating external user management will remove user and group management options from Confluence. Your users will also no longer be able to edit their full name or email address inside Confluence (if they want to, they would have to do so in JIRA). To do this:

1. Log into Confluence using your JIRA account.
   
   
2. Go to the Administration Console and click General Configuration in the left panel
   
   
3. Click 'Edit' at the bottom of the 'Options and Settings' screen.
   
   
4. Select 'ON' beside 'External User Management'.
   

関連トピック