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 to JIRA so that 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 log in to Confluence.

Read Before Proceeding

1. The examples used in this document are based on Tomcat Application Server and the MySQL database. 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. Shut down Confluence.

Step Two: Setting up a Datasource to JIRA's Database

In order to delegate all user authentication attempts and group membership queries to JIRA, Confluence needs to be 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 there is an existing block of <Resource> in the <context> descriptor, please do not replace it. Rather, just add the following <Resource> block inside the <context> descriptor.

If you are running Confluence WAR/EAR version separate to JIRA, or under JIRA standalone 3.3 and later, your Confluence context will be in the confluence.xml file. If you are running Confluence standalone separate to JIRA, or Confluence WAR/EAR version under an older version of JIRA, your Confluence context will be in the server.xml file. You should never have a Confluence context in both.

If you are running Confluence standalone (or Confluence inside a JIRA standalone) 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.

The DataSource configuration below is using MySQL as an example. You will need to modify these settings according to the database that you are using.

• 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: Modifying osuser.xml

Please perform this step after you have completed the Confluence setup wizard.

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: Customising osuser.xml

In some cases you may need to customise the behaviour of the JiraJdbc classes. You can do this by setting properties within the osuser.xml file.

This process is documented here.

Step Six: Modifying atlassian-user.xml

This step is only applicable for Confluence 2.7 and later .

Please comment-out/remove the following line from your <Confleunce-Install>/confluence/WEB-INF/classes/atlassian-user.xml file:

<hibernate name="Hibernate Repository" key="hibernateRepository"  description="Hibernate Repository" cache="true"/>

and add this line instead:

<osuser name="OSUser Repository" key="osuserRepository"/>

Step Seven: 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
   • Start up Confluence. Log in using your JIRA account, and go to Administration and then Global Permissions. Now assign the 'can use' permission to your desired JIRA groups.
     

     In order to use Confluence, users must be a member of the confluence-users group (or have Confluence 'can use' permission).

      
      
     

Step Eight: 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 switch external user management on:

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

For answers relating to JIRA User Management, click on any query below.

Troubleshooting

Confluence login page loads with 'NullPointerException' system error

If the page loads with 'System error' with cause 'java.lang.NullPointerException at com.atlassian.user.impl.osuser.OSUUserManager.getOpensymphonyUser(OSUUserManager.java:85)' and output logs shows 'user.provider.jdbc.BaseJDBCProvider] init Could not look up DataSource using JNDI location' error, either the Resource for the DataSource is not being loaded by the application server, or it is being loaded but the resource names do not match. Check the names first, so if '/confluence/WEB-INF/classes/osuser.xml' specifies a datasource named 'java:comp/env/jdbc/JiraDS', the datasource specified in server.xml or confluence.xml must be 'jdbc/JiraDS'.

Confluence login page loads with 'HTTP Status 404' and output log shows 'java.lang.ClassNotFoundException' for driver, eg 'com.mysql.jdbc.Driver'

Missing the database driver library. On standalone or Apache Tomcat, download the database jar to the common\lib directory.

Confluence login page loads but login fails with 'Username and password are incorrect' and output log shows 'Access denied for user'

Caused by an incorrect database URL or login in the datasource.

Confluence login page loads but login fails with 'Username and password are incorrect' and output log shows 'Cannot create JDBC driver'

If your log outputs an error with "FATAL [user.provider.jdbc.JDBCCredentialsProvider] Could not list users. org.apache.commons.dbcp.SQLNestedException: Cannot create JDBC driver of class '' for connect URL 'null'", you are using the incorrect Tomcat format for specifying the Datasource resource. You should check your Tomcat version and use the alternative format.

I cannot get my JIRA integration to work, where can I get technical support?

RELATED TOPICS

Delegate user management to use JIRA logins

Migrating users from Confluence to JIRA

Revert from JIRA to internal user management