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.

On this page:

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. If JIRA is using LDAP for authentication, you should not use JIRA for Confluence user management. Use Add LDAP Integration instead.
   
   
3. Always install Confluence with a new database. Do not attempt to use the existing JIRA database, with either JDBC or data source.
   
   
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. Do not add any spaces or content once Confluence installation is complete, apart from verifying that your Confluence instance is up and working, until you have completed the procedure on this page. Users in Confluence will no longer be valid once you switch over to using your JIRA users.
   
   
5. If you run into a problem, check the Troubleshooting section below.

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 already installed Confluence and completed the Setup Wizard.

1. Install Confluence and run the Setup Wizard:
   • If you are running JIRA standalone please follow these instructions for installing Confluence.
   • If you have JIRA deployed under your own Tomcat server, please follow these instructions.
     
     
2. Ensure that Confluence is running and has been set up, that is, you have completed the Confluence Setup Wizard and verified that you can create pages.
   
   
3. 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 EAR/WAR edition 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/WAR edition 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 are not 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 uses MySQL as an example. You will need to modify these settings according to the database that you are using.
• You should add the appropriate validation check for the connection pool to avoid intermittent problems authenticating.

Sample context descriptor for Tomcat 4.x and 5.0.x

<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 (or potentially .../lib for Tomcat version 6 and beyond).

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

Step Four: Modifying osuser.xml

1. Find the osuser.xml file in the /confluence/WEB-INF/classes folder and open it 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>
   

In this example, JiraDS is the name of the JIRA datasource you are sharing with Confluence. If you have changed the name in Step Two of this documentation, you will need change all occurrences 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 or 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 the confluence-users and confluence-administrators groups in JIRA.
   
   
2. Add yourself to both these groups.
   
   
3. To give your existing JIRA users access to Confluence, you have two options.
   • Option 1: Manually edit the groups of these users inside JIRA and give them membership to one or both of these confluence groups.
   • Option 2: 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.

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 troubleshooting, see the JIRA Integration FAQ.

関連トピック