Single Sign-on to JIRA with SiteMinder

So you've been using JIRA, it's going well - and now you want to move away from the default internal directory or the built-in LDAP support. This may be because you've outgrown it, because you want easier sign-on, or because there's been a shift in the environment that you're supporting. No matter what, you're about to go on a ride.

JIRA supports Seraph authentication - both are from Atlassian. The great thing about this is it will allow you to write your own authenticator class in Java. The bad part about this is it's very poorly documented.

Your first search will probably land you here: https://docs.atlassian.com/atlassian-seraph/latest/sso.html

At the time of this writing, that article is over a year old and it doesn't get you quite where you need to go. Furthermore, it doesn't even tell you where to get started.

As you search around more, you'll find various Confluence articles at Atlassian, a few GitHub projects, and some questions on answers.atlassian.com. I'm going to try to save you some of the effort by giving the details of what I did to get an authenticator up and running.

As a note - my environement is Windows based so your steps may vary.

Here's a brief overview:

  1. Download the SDK: https://developer.atlassian.com/display/DOCS/Set+up+the+Atlassian+Plugin+SDK+and+Build+a+Project (web archive here)
  2. Don't worry about getting the Eclipse editor - you can get by with a simple editor like Notepad++ for this.
  3. After you've installed the Atlassian SDK, don't use it for anything but building!

I saw a few different (misleading) posts on how to build the authenticator. The bottom line is that using atlas-create-jira-plugin command doesn't work, and nor does atlas-create-jira-plugin-module.

It seems that this authenticator is some strange mix in-between. It's a type 1 plugin which means it has to be "installed" (copied) into the WEB-INF/lib

Let's get started...

The first thing the documentation tells you to do is implement the com.atlassian.seraph.auth.DefaultAuthenticator; class. I've found this to have issues, and had much better success with: com.atlassian.jira.security.login.JiraSeraphAuthenticator.

See my BitBucket project for my quick implementation of this class with very limited features: https://bitbucket.org/docsaintly/jira-sso-with-siteminder.

From here, you just have to implement: public Principal getUser(HttpServletRequest request, HttpServletResponse response)

This function returns a Principal object which is basically just the username of the person who is authenticated. You can use the super.getUser(request,response) to do this for you without much work.

The rest is up to you and how you want to choose what to do. As you can see in my implementation, I look for the variable "username" in my header that I've been passed from SiteMinder. If you use a different variable, just change this.

From here, I have to strip off the domain name that is passed along with the username. I could have also retrieved the cookie itself because that contains the username without the domain. It's all up to you what you want to do. You can find other examples online that go as far as to automatically create new users in the system after they've been authenticated through the SSO. This is where you get to determine how it figures out which user in JIRA gets mapped to the user coming from the SSO.

Once you have your code written, you can drop into the command prompt and run atlas-package assuming you have the Atlassian SDK installed.

This will alert you of any errors, and once it is successful you can copy your compiled .jar file to the WEB-INF/lib folder of your JIRA installation.

The one thing left to do is configure your seraph-config.xml file according to Atlassian's SSO documentation to configure where the login and logout of Seraph will point.

After you've done all this, restart your JIRA instance and watch the atlassian-jira.log as it starts up to see if your authenticator loaded properly.

There are a few other things I've done that weren't documented, but I haven't confirmed if they are necessary.

With the way I've written the authenticator, if you authenticate through SiteMinder and land on the system but don't have an account - you'll be faced with the login page. You probably don't want this - so you'll want to disable the login gadget in the jpm.xml file according to this post: https://community.atlassian.com/t5/Answers-Developer-Questions/Disable-JIRA-Login-page-with-Seraph-SSO/qaq-p/572577

The final thing is to set up some filters in Tomcat's web.xml file to point certain activities towards Seraph's Login and Security pages. This is the part I know the least about and will do more investigation on:

<!-- Seraph Filters for SiteMinder SSO --><filter><filter-name>login</filter-name><filter-class>com.atlassian.seraph.filter.LoginFilter</filter-class></filter><filter><filter-name>security</filter-name><filter-class>com.atlassian.seraph.filter.SecurityFilter</filter-class></filter><!-- Seraph Filter Mapping for SiteMinder SSO --><filter-mapping><filter-name>login</filter-name><url-pattern>/*</url-pattern></filter-mapping><filter-mapping><filter-name>security</filter-name><url-pattern>/*</url-pattern></filter-mapping>

Credits for this post go to MANY people who have provided snippets of code and help for a portion of JIRA/Seraph that is very poorly documented.

Comments