Integrating JIRA and SSO Using CAS

by Mike Brown | Aug 1, 2017 | Ascend Blog, Project Atlassian

By default, Atlassian JIRA has an internal directory, integrates with LDAP / Active Directory, and integrates with a Single Sign On (SSO) solution: Crowd. However, a growing number of administrators are looking to integrate their Atlassian solutions across their enterprise Central Authentication Service (CAS). We decided to write this blog based on the original work put together by the JASIG team: CAS Configuration. The original code repository can be found here if you’d like to build the JAR files yourself: https://github.com/apereo/java-cas-client. A more detailed account along with code snippets can be found on our blog here: https://ascend.zellecloud.com/ascend-blog.

While the JASIG team created an excellent entry, we wanted to build on its success by adding easy-to-find download links, updated XML entries, and some additional details or directories / locations. This entry includes details on integrating with JIRA 7.x running on a Linux-based server.

The five steps we are covering here include:

Shutdown JIRA + Know your File Locations
Copy the JAR Files
Modify web.xml
Modify seraph-config.xml
Start JIRA

While this is meant to be an overview and will help in getting your JIRA to communicate with your CAS system, it is not meant to be a full setup of CAS, or a full JIRA configuration / set up as well. This article is for semi-advanced users and administrators. But, with that said if you have any questions as you go through it, please feel free to reach out to us: info@ascend.zellecloud.com.

Step 1: Shutdown JIRA + Know your File Locations

First, make sure JIRA is shut down.

All files discussed here will exist in the following locations (note, JIRA_INSTALL by default is set to the /opt/atlassian/jira/atlassian-jira/ directory). The list of the files to be modified / copied are below as well as their locations:

seraph-config.xml: JIRA_INSTALL/WEB-INF/classes
web.xml: JIRA_INSTALL/WEB-INF/
CAS Client for Java Core: JIRA_INSTALL/WEB-INF/lib (needs to be copied here)
CAS Client for Java Atlassian Integration (for JIRA 7): JIRA_INSTALL/WEB-INF/lib

NOTE:
You can download the updated CAS clients (v3.3) that will be used along with the Jira7 JAR files from our Bitbucket repository here (download both files): https://bitbucket.org/mbrown_ascend/jira-cas-integration/downloads/

Step 2: Copy the JAR Files

After you have downloaded the files above (CAS Client for Java Core v3.3.3 + CAS Client for Java Atlassian Integration v3.5), copy both of these JAR files both into the JIRA_INSTALL/WEB-INF/lib/ file directory.

Step 3: Modify web.xml

Open up web.xml in your favorite text editor. We used VIM for most of these modifications. Around line 374, just above the “THIS MUST BE THE LAST FILTER IN THE DEFINED CHAIN” comment, add the following code (Wherever it says to add your specific information):

<!-- CAS:START - Java Client Filters -->
 
<filter>
   <filter-name>CasSingleSignOutFilter</filter-name>
   <filter-class>org.jasig.cas.client.session.SingleSignOutFilter</filter-class>
</filter>
<filter>
  <filter-name>CasAuthenticationFilter</filter-name>
  <filter-class>org.jasig.cas.client.authentication.AuthenticationFilter</filter-class>
  <init-param>
    <param-name>casServerLoginUrl</param-name>
    <param-value> Include your CAS login here </param-value>
  </init-param>
  <init-param>
    <param-name>serverName</param-name>
    <param-value> include your JIRA url here </param-value>
  </init-param>
</filter>
<filter>
    <filter-name>CasValidationFilter</filter-name>
    <filter-class>org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter</filter-class>
    <init-param>
        <param-name>casServerUrlPrefix</param-name>
        <param-value>Include your CAS login here</param-value>
    </init-param>
    <init-param>
        <param-name>serverName</param-name>
    <param-value>include your JIRA url here</param-value>
    </init-param>
    <init-param>
        <param-name>redirectAfterValidation</param-name>
        <param-value>true</param-value>
    </init-param>
</filter>
 
<!--- CAS:END -->

Next, around line 627, there will be a filter mapping for your login, something like this:

    <filter-mapping>
        <filter-name>login</filter-name>
        <url-pattern>/*</url-pattern>
        <dispatcher>REQUEST</dispatcher>
        <dispatcher>FORWARD</dispatcher> <!-- we want security/login to be applied after urlrewrites, for example -->
    </filter-mapping>

Above the filter mapping code listed above, copy and paste the following:

<!-- CAS:START - Java Client Filter Mappings -->
 
<filter-mapping>
   <filter-name>CasSingleSignOutFilter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>
<filter-mapping>
    <filter-name>CasAuthenticationFilter</filter-name>
    <url-pattern>/default.jsp</url-pattern>
</filter-mapping>
<filter-mapping>
    <filter-name>CasValidationFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>
 
<!-- CAS:END -->

You can just copy / paste this code directly. After you have finished, save the web.xml file (in the VIM editor type ESC and then “:wq”).

Step 4: Modify seraph-config.xml

Next, you must make the following modifications to the seraph-config.xml file. In your seraph-config.xml file, there should be series of parameters. This is where you will make the modifications. Look at the code below, once again any area below that states “add your CAS URL…” is what you will need to modify.

<init-param>
    <!--
      The login URL to redirect to when the user tries to access a protected resource (rather than clicking on
      an explicit login link). Most of the time, this will be the same value as 'link.login.url'.
    - if the URL is absolute (contains '://'), then redirect that URL (for SSO applications)
    - else the context path will be prepended to this URL
 
    If '${originalurl}' is present in the URL, it will be replaced with the URL that the user requested.
    This gives SSO login pages the chance to redirect to the original page
    -->
    <param-name>login.url</param-name>
    <!--<param-value>/login.jsp?os_destination=${originalurl}</param-value>-->
    <param-value>add your CAS URL here</param-value>
</init-param>
<init-param>
    <!--
      the URL to redirect to when the user explicitly clicks on a login link (rather than being redirected after
      trying to access a protected resource). Most of the time, this will be the same value as 'login.url'.
    - same properties as login.url above
    -->
    <param-name>link.login.url</param-name>
    <!--<param-value>/login.jsp?os_destination=${originalurl}</param-value>-->
    <!--<param-value>/secure/Dashboard.jspa?os_destination=${originalurl}</param-value>-->
    <param-value>add your CAS URL here</param-value>
</init-param>
<init-param>
    <!-- URL for logging out.
    - If relative, Seraph just redirects to this URL, which is responsible for calling Authenticator.logout().
    - If absolute (eg. SSO applications), Seraph calls Authenticator.logout() and redirects to the URL
    -->
    <param-name>logout.url</param-name>
    <!--<param-value>/secure/Logout!default.jspa</param-value>-->
    <param-value>add your CAS LOGOUT URL here</param-value>
</init-param>

After you have finished with this modification, scroll down to around line 93, and comment out SSOSeraphAuthenticator and JIRASeraphAuthenticator lines:

<!-- CROWD:START - If enabling Crowd SSO integration uncomment the following SSOSeraphAuthenticator and comment out the JiraSeraphAuthenticator below -->
    <!--
    <authenticator class="com.atlassian.jira.security.login.SSOSeraphAuthenticator"/>
    -->
<!-- CROWD:END -->
 
    <!-- CROWD:START - The authenticator below here will need to be commented out for Crowd SSO integration -->
    <!-- <authenticator class="com.atlassian.jira.security.login.JiraSeraphAuthenticator"/> -->
    <!-- CROWD:END -->

Add the following to this section instead:

<authenticator class="org.jasig.cas.client.integration.atlassian.Jira7CasAuthenticator">
        <init-param>
            <param-name>casServerUrlPrefix</param-name>
            <param-value>include your cas server here</param-value>
        </init-param>
        <init-param>
            <param-name>serverName</param-name>
            <param-value>include your JIRA server URL</param-value>
        </init-param>
</authenticator>

From there, save and close the file.

Step 5: Start JIRA

After you start JIRA instance, go to a browser and type in your JIRA URL. You will be re-directed to your CAS Client.

If you are having issues with your configuration, please reach out to us anytime! We have completed CAS configurations in multiple environments using different versions of CAS. If you have any questions about this blog or about integrating your Atlassian Tool with multiple SSOs, send us an email at info@ascend.zellecloud.com.