This page last changed on Mar 20, 2007 by ktran.

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 With Group Management 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 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 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.

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:
    <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

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: 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.

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

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'.

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

Troubleshooting

Confluence login page loads with 'NullPointerException' system error

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

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

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

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


osuser.xml (text/xml)
osuser_original.xml (text/xml)

See http://jira.atlassian.com/browse/CONF-950. You apparently need to run through setup with external user management turned off. Wheh you finish setup, you can turn on external user management.

Posted by asdflkj@lkjasdf.com at Jun 03, 2004 16:44

Are there any pointers for integrating JIRA+Confluence into Weblogic/Jetspeed portal and delegate the user management to these portals. This will help in having a single sign on for the entire portal not just JIRA+Confluence.

You guys are doing a fantastic job.

Posted by nitinzep at Jan 28, 2005 16:21

I completed this process successfully. I created a project in JIRA giving the link to a confluence page for project documentation.
I log into JIRA and click on this link but i am asked to login again.
I also created a link on one of the confluence pages to a JIRA roject page, clicking on this link in confluence also takes me to the JIRA login page nstead of the project page. Is there a way to get over this.

Posted by nitinzep at Jan 28, 2005 16:50

Hi Nitin,
It's probably a good idea to shoot emails through to confluence-support@atlassian.com , comments won't always have a timely response.

Currently, we do not have single sign on between applications. While users can be shared across applications they must authenticate for each.

Cheers,
Nick

Posted by nick@atlassian.com at Feb 16, 2005 23:44

The jira Context stuff in in the jira.xml file on my installation. Where would the confluence context stuff then go?

CHarlie

Posted by at Apr 11, 2005 18:27

you can create them in tomcat_home/conf/catalina/localhost

Posted by at Apr 18, 2005 12:11

Note, in the example to "uncomment this block":

<provider class="bucket.providers.CachingProfileProvider">

Should be:

<provider class="bucket.user.providers.CachingProfileProvider">
Posted by jason.dillon@paybytouch.com at Jun 16, 2005 16:09

Are there any pointers for integrating JIRA+Confluence into Resin. I don't know what will Tomcat <context> be in Resin!!!!

Posted by at Jun 25, 2005 15:05

The most crucial step in delegating user management is setting up a datasource in your Confluence webapp (regardless of what application server you are using) to point to JIRA's database.

So in your resin.conf, you need a datasource that looks something like this:

<resource-ref>
    <res-ref-name>jdbc/JiraDS</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <init-param driver-name="org.postgresql.Driver"/>
    <init-param url="jdbc:postgresql://localhost/jiradb"/>
    <init-param user="postgres"/>
    <init-param password="postgres"/>
    <init-param max-connections="20"/>
    <init-param max-idle-time="30"/>
</resource-ref>

Obviously you have to ensure that the appropriate JDBC drivers are in the classpath for your chosen application server too.

The rest of the setup steps should be similar.

Cheers,
Dave

Posted by dave@atlassian.com at Jul 01, 2005 16:24

We are currently using LDAP for authentication ( basically it is just password checking ). Can you do a mix of it ( JIRA/Confluence/LDAP ) ? ie Confluence will use JIRA's user database but authentication ( password checking ) will be done through LDAP?

Posted by bhkwan at Jul 05, 2005 15:39

Yes, that is possible.

Simply follow the steps in How to delegate user management in Confluence to JIRA and Enable LDAP authentication to setup this environment.

Posted by jens@atlassian.com at Jul 05, 2005 20:50

Is it possible to take setup an install of Confluence with external user management, and then import data from an install which was not setup to delegate to JIRA?

e.g. can I follow the direction above, then:

  • import a backup?
  • import a space at a time?
  • will it autocreate user entries?
  • will it overwrite existing user entries?
Posted by jayshao at Aug 22, 2005 15:02

Firstly, unless you intend this, importing a site backup from another install of Confluence will wipe out everything in your current install.

If you do intend this, user entries will not be autocreated in JIRA (remember the bridge from Confluence to JIRA is read only - Confluence cannot write to JIRA's user database).

Space imports are fine.

Cheers,
Dave

Posted by dave@atlassian.com at Aug 23, 2005 20:07

If you have an existing Confluence setup and running, and you are deploying Jira, but want to defer all user management to Jira (i.e. so there will be only one user profile, one place to mange permissions, etc) can you take all you existing users/groups/profiles from the confluence database, and import them into the jira user database?

Posted by ricardo.sueiras@uk.pwc.com at Sep 11, 2005 18:34

You could transfer the users via a script or sql directly. However, you will have to take care of the user email since the property set is stored in a different column in Jira. You will also have to join the user groups and add them into the jira database.

Another way would be to create the users via the remote API. You will have to write a script which queries your database for the right data and creates the user in Jira via the remote API. The drawback there is that the user will have to change his password since there is no way to access and insert the current password.

If you need any assistance with this task, please let us know and send an email to: confluence-support@atlassian.com

Cheers,
Jens

Posted by jens@atlassian.com at Sep 12, 2005 03:17

Thanks Jens.

We will be using a custom authenticator so passwords will not be an issue, as the password stored in the database will not be used.

When you say "join the user groups and add them into the jira database" what exactly do you mean? Do you mean add all the users into the "jira-users" group (or equiv) that is stored in the jira database?

Thanks.

Posted by ricardo.sueiras@uk.pwc.com at Sep 12, 2005 05:31

Ricardo,

in order to keep the permissions set in Confluence working, you will have to make sure that you move over all relationships between users and groups to your jira database.

However, it is a little bit to complex to discuss this in the comment section of this page. Please write us an email to confluence-support@atlassian.com and we will happily assist you with the migration of your user database.

Cheers,
Jens

Posted by jens@atlassian.com at Sep 12, 2005 20:09

Is there a particular reason that the first step of the directions specifically say that the WAR version should be installed?

I went through the whole process of setting up a clean Tomcat 5.5.12 instance, adding the Confluence webapp, etc.  It ran, but I quickly blew up with a Java out of memory error.  If there are any particular pointers in tuning a clean tomcat install, that would be nice.

But irrelevant to that, I decided to just go back to my original standalone Confluence install and add the JiraDS config, and that seemed to work just fine.  (once i figured out that needed to use the Tomcat 4.x syntax for the data source config)

Posted by elliottjf at Dec 15, 2005 13:29

Hi Joe,

No, there's not particular reason that I know of. You should be able to configure it with Confluence standalone with no problems.

If you are getting OutOfMemoryErrors, have a look at [this page|http://confluence.atlassian.com/display/DOC/Memory+usage+and+requirements] on how to increase the amount of memory available to Confluence.

Jeremy.

Posted by jeremy@atlassian.com at Dec 15, 2005 23:12

It's nice to delegate the user management to Jira, but there is something missing in this solution. If I don't delegate U.M., then when new users are added, they are automatically a member of the "confluence-users" group. In Jira, they are only in "jira-users" when a user is created. How can I get Jira to put the user in "confluence-users" too? I want my Confluence & Jira to be as "hands-off" (i.e. no administrator intervention) as possible.

(This Confluence & Jira setup is within a corporate intranet whereas everyone is trusted.)

I've thought of creating a database trigger but there is a concern that I don't know if it is a problem. The "id" attribute in Jira's database tables have no set default value. Presumably they are set by Jira and not the database (bad DB design IMO, but any way...). If my trigger were to choose the next highest ID, it's plausible there may be a conflict because Jira might have the highest id cached already.

Atlassian, please offer some pointers.

Posted by dsmiley at May 02, 2006 07:58

Does giving  jira-users the 'can use' permission in Confluence solve your problem?

cheers,
dz 

Posted by davidz at May 08, 2006 16:26

Hmmm, that's an interesting idea. Can someone at Atlassian confirm that this technique will work fine? Some questions that come to mind:

  • Is "confluence-users" needed then?
  • Is there a template for new spaces so that I can ensure that the jira-users group has access?
Posted by dsmiley at May 09, 2006 07:33

In Jira, navigate to Administration, Global Permissions.  Add 'confluence-users' to the"Jira User" permission.   All groups with "Jira User" permission are assigned to new users.

Posted by davidruhde at Jul 20, 2006 14:45

Thanks, I didn't know about that.

Posted by dsmiley at Jul 21, 2006 09:42

Allright, so, using these directions, I cannot get this to work. I have questions at every step of the instructions!

"Step One: Installing Confluence"  It says "Preform installation against a new database...yadda yadda" Is that referring only to a "JIRA deployed under your own tomcat" installation? It seems like it is, but it might not be.

"Ensure that Confluence is running" -- does this include going through the "Confluence setup wizard" or just seeing if Confluence brings up the setup wizard screen?

 "Step Two:..." It says, "In Tomcat..." but how can I tell which version of Tomcat? It is very unclear from the instructions here.  In fact, all of Step Two is unclear.

Which version of Tomcat (I am running JIRA 3.6.2 standalone and Confluence 2.2.8 standalone)?  But I am trying to run Conflunce "under" JIRA.  In fact, I had that part working...

Where do I specify the JDBC resource? In the Confluence installation config files? Or in the JIRA? I.e. I have a "server.xml" file(s) and a "confluence.xml" file(s) -- which do I use:

./jira/conf/server.xml

./confluence/conf/server.xml

./jira/conf/Catalina/localhost/confluence.xml

"Step Three: JDBC Driver"

Do I need to install the JDBC driver for Confluence? Or is having it in the JIRA installation enough?

If yes, then where? Can I just copy the one from the JIRA install? 

"Step Four: Modify OSuser"

Well, first of all, there is a warning "Do this first!" which comes AFTER the whole set of instructions.  Hello? Put the warning FIRST! In any case, the warning is unclear.

"Please perform this step after you have completed the Confluence setup wizard." Well, how? The Confluencee Setup Wizard has two options. Do I just choose "Standard Installation"? Well that doesn't make sense because I am going to use the JIRA database, aren't I?  Also, the "Wizard" has a configure user screen/step.  Why should I configure a user if I am going to be using all JIRA users anyways?

So you can  see I am having rather a lot of difficulty.

Here is my intended setup:

JIRA Installed in /opt/jira  (WORKS)

Confluence installed in /opt/confluence (Works if not connected to JIRA in any way)

Configure JIRA to run on http://host.name:8080/ (Works!)

Configure Confluence to run on http://host.name:8080/confluence (This worked too, until I tried to go past step one!)

Thanks for any help here! 

Posted by jeffrey@jhu.edu at Aug 29, 2006 15:52

Hi Jeffrey,

Thanks for the feedback. We've made some updates to the document above, and followed this up with a support case.

Please let us know if there's anything else we can help with.

Regards,
Matt

Posted by mryall at Sep 04, 2006 00:51

Can somebody update the links? Thank you.

Posted by mumebuhi@gmail.com at Oct 26, 2006 13:58

I am trying to do the following:
1. Confluence to use LDAP only for authentication. (I have this working.)
2. JIRA to use LDAP also only for authentication. (I have this working.)
3. JIRA maintains its users and groups in its own database. (I have this working.)
4. Confluence to utilize JIRA's database for the group management.

On http://confluence.atlassian.com/x/Ugs, the first note says:

1. If JIRA is using LDAP for authentication, you should not use JIRA for Confluence user management. Use Add LDAP Integration With Group Management instead.

The refered page actually discusses using LDAP for user and group management, which unfortunately does not fit my need. Does anybody know how to solve the point #4 above?

Thank you.

Posted by mumebuhi@gmail.com at Oct 26, 2006 15:36

Sorry about it

Ldap integration
Delegate User management to JIRA

Posted by ivan@atlassian.com at Nov 08, 2006 23:25
Document generated by Confluence on Mar 22, 2007 20:55