Sorry about the Syntax, it's for my internal DokuWiki.

JIRA 4.3+ with mod_auth_kerb SSO

Goal

Users should transparently log in to JIRA with AD domain credentials.

Overview

Apache authenticates users using mod_auth_kerb and passes the authenticated username to JIRA through an AJP proxy. JIRA uses a custom Seraph filter which checks for the remote_user variable set by Apache and logs the user in automaticaly.

Installation

  1. Install Jira using the standard install, listening on port 8080
    • Allow port 8080 through the firewall
  2. Setup LDAP user directory
    • Test logging in using your AD credentials
  3. Setup apache to act as a proxy to Jira using AJP
    • Add this line to the server.xml file, around line 114.
      /opt/atlassian/jira/conf/server.xml
      <Connector port="8009" redirectPort="8443" enableLookups="false" protocol="AJP/1.3" URIEncoding="UTF-8" tomcatAuthentication="false"/>
    • Check the attached “jira_proxy.conf” file for the apache configuration.
  4. Install mod_auth_kerb and configure to authenticate against your AD
    • There is plenty of documentation out there on how to do this, I have also attached my relevent configuration files.
    • Set up a location like /private and test against that, until you have the authentication working successfully, then apply it to the JIRA proxy created in the next step.
  5. Add “anguswarren.jira.RemoteUserJiraAuth.jar” to the WEB-INF/lib directory
  6. Edit seraph-config.xml to match below:
    /opt/atlassian/jira/atlassian-jira/WEB-INF/classes/seraph-config.xml
    REPLACE THIS:
    <authenticator class="com.atlassian.jira.security.login.JiraSeraphAuthenticator"/>
    WITH THIS:
    <authenticator class="anguswarren.jira.RemoteUserJiraAuth"/>
  7. Restart JIRA and Apache
  8. Check to see if it is now working.
    • If it's all OK, block port 8080 from the firewall and only allow 8009 from the Apache server (localhost in my case.)

Notes

Kerberos

Kerberos is a pain. Check that the SPN is valid against the hostname that you are connecting to and that you do not have a duplicate SPN configured in AD. The following code will check for duplicate SPN's

ldapsearch -h dc01.domain.local -x -W -D "domainadmin@domain.local" \
-b "DC=DOMAIN,DC=LOCAL" 'serviceprincipalname=*' serviceprincipalname | \
grep 'Name:' | sort | uniq -d

To Generate your keytab, the easiest way is to run this command from the linux host after joining the domain.

net ads keytab add HTTP -U domainadmin

If you are using a virtual server and the name you connect with is not the same as the domain computers name, you will need to generate a keytab for the second hostname. At my company, the computers name is SupportServer but we are connecting using jira.domain.local. Authentication will fail if the keytab does not match the hostname/fqdn you connect to (and the PTR record :(). To generate a keytab for another hostname:

  1. Create a new user account for the SPN/keytab to be bound with, set the password never to expire.
  2. From the windows command line run the following command (obviously you will need to replace my values to match your enviroment)
    • ktpass -princ HTTP/jira.domain.local@DOMAIN.LOCAL -out C:\jira.domain.local.keytab -mapuser jira-kerb@domain.local --pass userspassword
  3. Move the keytab to the correct location on the apache host. (specified in the apache config file for your virtual host)

Firefox

Open about:config and change add the JIRA url to 'network.negotiate-auth.trusted-uris'

Internet Explorer

First, add the JIRA url to either the Trusted sites or the Intranet zone. Once you have done that, either

  • set the security settings for that zone to allow “automatic logon with the current username and password.”
  • OR the lazy (efficient) way: Set the security level for the zone to “Low”