Shibboleth Authenticator for Confluence

Name Shibboleth Authenticator for Confluence
Vendor Shibboleth Authenticator for Confluence Team
Authors Chad LaJoie, Gary S. Weaver, Bruc Liong, Juha Ojaluoma, Vladimir Mencl
Homepage http://confluence.atlassian.com/display/CONFEXT/Shibboleth+Authenticator+for+Confluence
Categories Single Sign-on and Authentication
Issue Management http://developer.atlassian.com/jira/browse/SHBL
Version 1.5.1 (note: version works with Shibboleth 1.3+ and Shibboleth 2.0+)
Availability v1.0-1.2 works with Confluence 2.3+, v1.3+ tested with Confluence 2.9.2, 2.10.2, 3.0 but may work in Confluence 2.3+ (please test and let us know)
State Stable
License Open Source (v1.0-v1.2 Apache, v1.3+ BSD)
Price Free
Release Docs http://confluence.atlassian.com/display/CONFEXT/Shibboleth+Authenticator+for+Confluence
Download JAR remoteUserAuth-1.5.1.jar
Download Sample Config remoteUserAuthenticator.properties
Download Source http://svn.atlassian.com/svn/public/contrib/confluence/shibboleth-authenticator/
For plugin v1.3+, please make sure to update your seraph config to use the new package name, so that the authenticator class is "shibauth.confluence.authentication.shibboleth.RemoteUserAuthenticator". For versions prior to plugin v1.3 continue to use "edu.georgetown.middleware.confluence.RemoteUserAuthenticator".

Overview

Shibboleth Authenticator for Confluence is a seraph authenticator for Confluence for Shibboleth (tested with Shibboleth 1.3 and 2.0).
Shibboleth according to its site is "a standards based, open source software package for web single sign-on across or within organizational boundaries. It allows sites to make informed authorization decisions for individual access of protected online resources in a privacy-preserving manner". Basically, it is an open-source Single Sign-on solution that supports "federations", so that you could login once for all sites/services in all organizations (companies, universities, etc.) that are in the same federation (although you don't have to set Shib up that way if you don't want to or can't).

The Shibboleth Authenticator for Confluence basically takes the HTTP header that Shibboleth passes on to Confluence (usually REMOTE_USER) as the user's username (id) and either creates or updates a Confluence user in Confluence via Confluence API and can manage the groups memberships of that user based on Shibboleth (mace) attributes that have been configured to be passed into Confluence from Shibboleth.

Those using Crowd with Shibboleth should instead use the Crowd Shibboleth Authenticator.

Installation

  • Copy the jar file above into Confluence's WEB-INF/lib directory (and backup existing file).
  • Copy the sample config file above into Confluence's WEB-INF/classes directory (and backup existing file).

Configuration

Support

This plugin is supported by those that use it (the best kind of support!). It is not supported by Atlassian yet. If you need assistance with functionality of the plugin itself please go to http://developer.atlassian.com/jira/browse/SHBL and search for your issue. If you find it, vote for it, watch it, and add a comment to let us know about it. If you can't find an existing ticket, please create one. If you do create a ticket, it helps us to have debug logging (see "How to Turn on Debug Logging" section below).

If you're having any trouble configuring Shibboleth or Apache/Tomcat with Shibboleth in-general, please first pose your question(s) on the shibboleth users list: shibboleth-users@internet2.edu. There are folks on that list using the authenticator as well. To subscribe to that list (which I'd suggest doing, if you haven't already) go to: https://mail.internet2.edu/wws/subrequest/shibboleth-users

How to Turn on Debug Logging

It helps to have debug logging of the plugin itself if something is wrong, so you can do the following to turn on debug logging, and then you can send the part of the log with the issue in the ticket (or attach the log as a file if the section is more than several lines long). To turn on debug logging, you can edit your .../confluence/WEB-INF/classes/log4j.properties file, add the following line and restart Confluence. Then after a login copy the relevant part of the confluence log into the Jira ticket in our Jira project or just attach it as a file:

For building Shibboleth Authenticator for Confluence from trunk and for Shibboleth Authenticator for Confluence v1.3+, use:

log4j.logger.shibauth.confluence.authentication.shibboleth=DEBUG, confluencelog

For Shibboleth Authenticator for Confluence v1.0, v1.1, and v1.2 use:

log4j.logger.edu.georgetown.middleware.confluence=DEBUG, confluencelog

(Those are assuming that you have "log4j.appender.confluencelog=org.apache.log4j.ConsoleAppender" defined above it, otherwise basically do whatever you need to to enable debug logging for that package.)

Development

If you'd like to get involved in this plugin's development, please let us know. Either leave us a comment on this page or feel free to contact us directly.

Version History

Version Date Description License Downloads
1.5.1 26 June 2009 Changes by Gary Weaver:
  • SHBL-23 - No mapper capable of processing role message should be logged DEBUG not WARN
 BSD remoteUserAuth-1.5.1.jar, remoteUserAuthenticator.properties
1.5 24 June 2009 Changes by Gary Weaver:
  • SHBL-21 - applying patch contributed from Michael Gettes because call to hasMembership and only calling addMembership when needed he determined was faster than only calling addMembership fix for SHBL-20 and some other possible config related issues not yet noticed. changed from using static values in config to instance. config instance itself is static and gets reloaded, so we don't want static member variables in the configuration instance itself, unless I'm missing something. we should consider moving to spring config for v2.0. config is a little out of hand now.
  • resolving SHBL-18. added null checks for header.fullname and header.email in config and updated config
  • Per some recent commits, there seems to now be a dependency on a newer version of seraph than may be included in earlier versions of confluence. In fact, upping the confluence version (tried several versions) didn't seem to include these. I looked at Atlassian's pom for confluence and it appears that only an earlier version of seraph (not atlassian-seraph) was referenced in earlier builds, and later builds don't include the version they may/may not use. We may end up needing to make changes to the code to make it work with older versions of Confluence, or we may need to change the dependencies (and maybe change versions?) to have a scope that would include these jars in the plugin rather than expect that Confluence provide them, in which case compatibility could be an ongoing issue.
  • Implementing patch submitted by Erkki Aalto written by Juha Ojaluoma for SHBL-14. Note that USER-254 possible bug related to this feature. This feature implements a new config option called update.last.login.date (true/false) in config that sets properties for the user in os_propertyentry even if not using osuser schema otherwise according to Erkki. Also updated License text.
    Changes by Bruc Liong:
  • resolve SHBL-16, hopefully improve response time slightly for SHBL-15. Also this has made updateLastLogin option to be optional, we're letting confluence to take care of that now. you will need to use the provided LoginFilter, edit web.xml: 
    <filter-name>login</filter-name>
<!-- <filter-class>com.atlassian.seraph.filter.LoginFilter</filter-class>  -->
<filter-class>shibauth.confluence.authentication.shibboleth.ShibLoginFilter</filter-class>
    Failure to use this Login Filter in web.xml will produce previous behaviour (i.e. before SHBL-16 fix; updateLastLogin is fully obeyed).
  • provide option dynamicroles.output.tolowercase to convert all group output to lower case by default.
  • change StringUtil.convertToUTF8 to have new String(getBytes("UTF-8"),"UTF-8") to see if UTF-8 conversion works, otherwise byte by byte conversion needs to be put in placed.
  • Revamp of group mapping, ref SHBL-6. Include capabilities of:
    • mapping with regex
    • inspecting only necessary headers for group mapping
    • purging roles with regex
    • multiple regex/mappers can be specified per header
 BSD remoteUserAuth-1.5.jar, remoteUserAuthenticator.properties
1.4 19 Dec 2008 Changes made by Vladimir Mencl to implemented two new features requested in SHBL-10 and SHBL-11:
  • SHBL-10: Addresses the issue where users dynamically assigned to groups would stay in these groups even when they no longer have (temporary) attributes that originally gained them the membership (such as codes of courses they are taking). Now, such groups can be specified with purge.roles, such as: 
    purge.roles=course-ABCD123,course-DCBA321

    (Requires update.roles=true)

  • SHBL-11: Restarting Confluence after adding a dynamic mapping would have too much impact on a production environment. With this feature, the module checks for changes to the configuration file (remoteAuthentication.propeties) on each user login and reloads the file if needed. It is also possible to set a minimal delay between the checks (in milliseconds, defaults to 0). To activate this feature, add the following to your configuration file: 
    reload.config=true
reload.config.check.interval=5000
BSD remoteUserAuth-1.4.jar, remoteUserAuthenticator.properties
1.3.1 5 Dec 2008 Changes made by Juha Ojaluoma for SHBL-5 to convert full name to UTF-8. Changes made by Gary Weaver and Bruc Liong to convert all header values to UTF-8. Changes made by Gary Weaver for SHBL-7 to add ability to handle multiple headers. Changes made Vladimir Mencl for SHBL-8 to fix issue with adding users to groups noticed in Confluence 2.9.2, along with subsequent fix in SHBL-9. Changes made by Gary Weaver to use BSD open-source license instead of Apache open-source license. Changes made by Gary Weaver to mavenize project and refactor. Should work in prior versions (Confluence 2.3+), but needs testing. Tested in Confluence 2.9.2. BSD remoteUserAuth-1.3.1.jar, remoteUserAuthenticator.properties
1.2 7 Mar 2008 Changes made by Bruc Liong of the Macquarie E-Learning Centre Of Excellence (MELCOE) to allow optional mapping of the values of 0-to-many HTTP Headers (fed by shib attributes) to Confluence group names (see properties file for how to do this). Changes made by Gary Weaver of Duke University to refactor config loading, constants, utility method, and added configuration VO. Apache remoteUserAuth-1.2.jar, remoteUserAuthenticator.properties
1.1 10 Dec 2007 Based on modifications by Gary Weaver of Duke University for Confluence 2.3-2.6.x along with additional checks/logging and some small refactoring. Version 1.1 should work with Confluence 2.3-2.6.x and possibly later versions. Apache remoteUserAuth-1.1.jar, remoteUserAuthenticator.properties
1.0 24 May 2007 Written by Chad LaJoie of Georgetown University and provided via https://svn.middleware.georgetown.edu/confluence/remoteAuthn/ and via in Internet2's confluence instance "spaces" at https://spaces.internet2.edu/display/SHIB/ShibbolizedConfluence. Version 1.0 worked with some Confluence versions prior to 2.3 (at least 2.2.x) and possibly worked up to Confluence 2.5.x. Apache remoteUserAuth-1.0.jar, remoteUserAuthenticator.properties

Troubleshooting

  • Logout may not work properly. A workaround is to alter the logout page to indicate that the user must completely close the browser application to logout. Editing the logout page messages can be done in the ConfluenceActionSupport.properties file (/confluence/WEB-INF/classes/com/atlassian/confluence/core/ConfluenceActionSupport.properties). ConfluenceActionSupport.properties has the following message properties for the logout page: title.logout, com.atlassian.confluence.user.actions.LogoutAction.action.name, successful.logout.message, and logout.login.again. A search on any of those should bring you to the right spot. While not recommended, you're also able to edit the logout.vm file (/confluence/logout.vm) directly. Additionally, you will likely need to update any language packs you've installed (and in Confluence 2.6.0+, ConfluenceActionSupport.properties is embedded within one of the jars in Confluence, so you may need to extract it to find the properties you need to update and then just create a ConfluenceActionSupport.properties that overrides those properties or create a new language pack where those properties are changed).
  • There may be an issue in v1.0 using the current authenticator with Confluence massive running with more than one node (CONF-9040) in which there is a unique constraint exception being thrown from Hibernate/Oracle when the user gets autocreated. The reason may be that the authenticator is being called at the same time by both nodes in when userManager.getUser() for the thread on server1 returns null and the userManager.getUser() is called for the thread on server2 which also returns null. The way this could be coded around is to do a try catch around createUser() and ignore unique constraint errors, however it doesn't seem right that the authenticator is being called on both servers for a single login, so this was logged as a bug in confluence. Please click on the link above and vote on this issue if you are getting unique constraint exceptions from the authenticator when using massive.
  • Migrating from os_user schema to atlassian-user schema (see How to Improve User Search Performance) will fail if you've used v1.0 of this authenticator to autocreate users, since it creates users with null passwords (even though the Confluence API supports creating users with null passwords, there was a bug in earlier versions of Confluence that cause Confluence to fail migration of these users - https://jira.atlassian.com/browse/CONF-9117). The two workarounds provided by Atlassian support are to arbitrarily set a password with those users that have null passwords prior to the migration (via SQL update) (this works, but it is a little scary since you are giving a password hash field an arbitrary value, and this value is migrated also to the users table in the schema) or upgrade to the latest version of Confluence that fixes this problem (2.5.8 and 2.6.x+).
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Comments (9)

 

  1. Dec 17, 2007

    Gary S. Weaver says:

    fyi - there is a good bit of historical and ongoing conversation about this plug...

    fyi - there is a good bit of historical and ongoing conversation about this plugin and Shibbolizing Confluence in the following mailing list: http://www.lsoft.com/scripts/wl.exe?SL1=ACAD-CONFLUENCE&H=LISTSERV.BROWN.EDU

    If you have a bug/development request, please signup for a free account at http://developer.atlassian.com/jira/ ) and add a ticket if one doesn't exist to http://developer.atlassian.com/jira/browse/SHBL. Be sure to put a watch on and vote on any tickets you are interested in.

    We welcome anyone who would like to contribute. Just leave us a comment on this page to let us know that you're interested!

  2. Dec 11, 2008

    Andy Brook says:

    Hey Gary, might be useful to summarise benefits of this approach, drivers for us...

    Hey Gary, might be useful to summarise benefits of this approach, drivers for use etc. Im no Shib expert and without going googling, am not yet clear on the environemt that may benefit most from it, even a summary would be handy, SSO yes but theres always more....

    1. Dec 11, 2008

      Gary S. Weaver says:

      Thanks for the feedback, Andy! Hope all is well. I just updated the overview...

      Thanks for the feedback, Andy! Hope all is well. I just updated the overview to give a brief summary of what this plugin is about.

  3. Feb 01

    Michael Alexander says:

    Gary et al, great authenticator!  We're not running Shibboleth, but we ...

    Gary et al, great authenticator!  We're not running Shibboleth, but we are using SAML and we our module sets the headers with role and group information in the same mechanism the shibboleth module is doing.  This module is very useful, I love the flexibility.

    1. Feb 02

      Gary S. Weaver says:

      Thanks, Michael! Chad, Bruc, and Vlad spent more time coding it than I did, ...

      Thanks, Michael! Chad, Bruc, and Vlad spent more time coding it than I did, and Scott Cantor has really helped also. So hats off you guys! Thanks again for the positive feedback, and feel free to get involved in its development.

      1. Feb 04

        Michael Alexander says:

        Still testing in the development environment, the only thing I've found with 2.8...

        Still testing in the development environment, the only thing I've found with 2.8.1 is an issue with login.action and permissions. I found the fix, though on CONF-13053, once the patched class files were in place, everything worked great.

        1. Feb 04

          Gary S. Weaver says:

          Thanks for sharing the info on your fix! Gary

          Thanks for sharing the info on your fix!

          Gary

  4. Jun 29

    Erkki Aalto says:

    I just tried 1.5.1 in our test environment. I did not change web.xml. Shibboleth...

    I just tried 1.5.1 in our test environment. I did not change web.xml. Shibboleth authentication seemed to work ( I did not test with multinationals in fullanme) but I could not login with a local account.

    1. Jul 01

      Gary S. Weaver says:

      Erkki, Glad to hear that Shibboleth authentication worked. That is the intent. ...

      Erkki,

      Glad to hear that Shibboleth authentication worked. That is the intent.

      Logging in using a "local account" (Confluence username and password or other authN method) while using the Shibboleth authenticator is not supported.

      If you have users and passwords in your Confluence DB that you still want to allow to login, here are some options:

      Option 1: Look into configuring your Shibboleth IdP to use Confluence users and passwords (and/or something else) as an allowable repository for authN credentials. You could ask the shibboleth-users@internet2.edu list to see whether that is possible and how to go about doing that. I wouldn't recommend doing this because the Shibboleth Authenticator for Confluence creates users in Confluence but does not store their passwords. That is intentional because the users in Confluence are still used for rights/permissions and for group memberships.

      Option 2: Disable Shibboleth or turn it off. Also disable the authenticator by modifying WEB-INF/classes/seraph-config.xml to undo the changes you've made to it. Restart Confluence after that. Then you can authenticate via Confluence itself but wouldn't be able to authenticate via Shibboleth. Once you are done doing whatever you need to do with the local account, re-enable Shibboleth, reapply changes to WEB-INF/classes/seraph-config.xml and restart Confluence. Then you will be able to login via Shibboleth but not authenticate via Confluence itself.

      Option 3: Develop some sort of mechanism for the Shibboleth to act as a user/group repository for Confluence. Then add that repo into atlassian-user.xml. (See customising atlassian-user.xml.) I'd imagine this would really take some time, and you'd basically not be using the Shibboleth SP at all (it wouldn't be "shibbolized", only using it as a repository, assuming you could configure it or extend it to act as one somehow, although I'd doubt this would be feasible).

      Best of luck,

      Gary

      P.S. - See also: http://developer.atlassian.com/jira/browse/SHBL-24