Okta

Okta Jira Authenticator 3.x Configuration Guide

Contents


Overview

In addition to providing the JIRA Cloud Web application through the Okta Application Network (OAN), Okta also supports single sign-on integration between Okta and the JIRA On-Premises SAML app. To configure the integration, you must install Okta's custom JIRA authenticator on your JIRA server.

The Current JIRA JAR Version History article lists the JIRA on-premise versions that support recent versions of the JAR. You can access the latest version of the okta-jira.jar file from the Okta Downloads page. Download the file before you begin the integration.

For more information about JIRA custom authenticators, see Single Sign-on Integration with JIRA and Confluence. For information about configuring provisioning for the app, see Configuring Provisioning for Jira On-Premise.

Note: To add the JIRA Cloud web app, see Applications.


Add the JIRA On-Premises SAML App to Okta

Note: Steps 5 and 8 below provide links to other documents for additional instructions.

  1. Download the appropriate version of the okta-jira.jar file from the Okta Downloads page. For information about which version of the JAR to download for use with your JIRA On-Premises SAML app, see Current JIRA JAR Version History. Later you will copy this file to your JIRA server.

  2. Select Applications from the Applications.

  3. Click Add Application, then search for JIRA On-Premises SAML.

  4. Click Add.

  5. Follow the onscreen prompts. Detailed instructions for this part of the installation here: Applications.

  6. When you have completed initial installation, the Home page of the newly-created app appears.

  7. Click the Sign On tab:

    jira_1.png

  8. In the Settings section, click View Setup Instructions to open the article How to Configure JIRA On-Premise SAML Application:

    jira_2.png

  9. Perform the steps in How to Configure JIRA On-Premise SAML Application. The procedure is summarized as follows:

    • Create a file okta-config-jira.xml on the JIRA server.

    • Paste the provided configuration into okta-config-jira.xml.

    • Update your [jira_webdir]/WEB-INF/classes/seraph-config.xml.

    • Copy okta-jira.jar to the [jira_webdir]/WEB-INF/lib directory.

    • Create a file okta-login.jsp in the [jira_webdir]/atlassian-jira directory and paste provided content into it.

    • Restart your JIRA service.


Additional Configuration (for JIRA Authenticator 3.x)

If you want to make any additional configurations please refer to okta-config-jira.xml example file below. It has all possible configurations with description for each block.

Short summary of configurable functionality:


Sample Files

okta-config-jira.xml File


<configuration>
    <applications>
        <application>
            <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/kh7zCAQGBWGUMQONCYNP">
              <md:IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
                <md:KeyDescriptor use="signing">
                  <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                    <ds:X509Data>
                      <ds:X509Certificate>MIICnTCCAgagAwIBAgIGASlMNawDMA0GCSqGSIb3DQEBBQUAMIGRMQswCQYDVQQGEwJVUzETMBEG
                        <!-- x509 certificate goes here -->
                      </ds:X509Certificate>
                    </ds:X509Data>
                  </ds:KeyInfo>
                </md:KeyDescriptor>
                <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
                <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
                <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://rain.okta1.com:1802/app/jira_onprem/kh7zCAQGBWGUMQONCYNP/sso/saml"/><md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://acme.okta.com/app/jira_onprem/1234567890/sso/saml"/>
              </md:IDPSSODescriptor>
            </md:EntityDescriptor>
        </application>
    </applications>
 
    <allowedAddresses>
        <!--If this section defined, it describes which IP addresses can use Okta Authenticator to log into Jira.
                This block takes precedence over spUsers block below.-->
        <oktaUsers>
            <ipFrom>192.168.3.10</ipFrom>
            <ipTo>192.168.3.220</ipTo>
        </oktaUsers>
 
        <!--If this section defined, it describes which IP addresses can use Native Jira autheticator (login/pass) to log into Jira.
        This block has lower priority than oktaUsers block.-->
        <spUsers>
            <ipFrom>*.*.*.*</ipFrom>
            <ipTo>*.*.*.*</ipTo>
        </spUsers>
    </allowedAddresses>
 
    <!--If this section defined, SP flow can be disabled for users,
        listed below. In this case they will be forced to login using their login/pass. -->
    <spUsers>
        <username>user1</username>
        <username>user2</username>
        <username>user3</username>
    </spUsers>
 
    <!--If this section defined, SP flow can be disabled for users assigned to groups in Jira,
       listed below. In this case they will be forced to login using their login/pass. -->
    <spGroups>
        <groupname>group1</groupname>
        <groupname>group2</groupname>
        <groupname>group3</groupname>
    </spGroups>
 
    <!-- If this section defined, authenticator won't be used for URLs listed below -->
    <spUrls>
        <url>servicedesk/customer/portal</url>
    </spUrls>
 
    <!-- This field is used to define whether you need to send LoginEvent to Jira.
        Some Jira plugins may rely on this event, so you can enable it if needed.
        Default value is false, which means no events will be sent
        Allowed values: true or false -->
    <fireLoginEvent>false</fireLoginEvent>
 
    <!-- This field is used to define whether you need to send UserAuthenticatedEvent to Jira.
        If you have configured any Directories in Jira
        and you want to apply deafult group settings configured in this Directory,
        you have to turn this flag on. Once it turned on - UserAuthenticatedEvent will be sent to Jira on first user login,
        and this event will trigger default group assignment process.
        Default value is false, which means no events will be sent
        Allowed values: true or false -->
    <fireUserAuthenticatedEvent>false</fireUserAuthenticatedEvent>
 
    <!-- This is requred section.
        Okta will use SAML authentication for URLs matching with listed below patterns -->
    <oktaProtectedUrls>
        <url>/secure/</url>
        <url>/browse/</url>
    </oktaProtectedUrls>
 
    <!-- This is required section.
        It is used to let Jira know to what URL it should redirect user for authentication -->
    <loginUri>https://acme.okta.com/app/jira_onprem/1234567890/sso/saml</loginUri>
 
</configuration>

okta-login.jsp File

This example file shows an example of a custom login page that determines how a particular user should be authenticated. First the Okta plugin is consulted to determine if the request should be handled by Okta or by the native JIRA login page.

If the request should be handled by Okta, the user's browser is redirected to Okta and the appropriate RelayState is appended so that Okta can redirect the user back to JIRA once they have successfully logged in.

Otherwise the user's browser is redirected to the login.jsp page of JIRA.


<%@ page import="com.atlassian.jira.authenticator.okta.OktaUrlUtils" %>
<%@ page import="org.apache.commons.lang3.StringUtils" %>
<%
    String relayState = request.getParameter("RelayState");
    StringBuilder loginUrl = new StringBuilder();
    if (OktaUrlUtils.shouldAuthenticateWithOkta(request)) {
        loginUrl.append(OktaUrlUtils.getOktaLoginUrl());
        if (StringUtils.isNotBlank(relayState) && !relayState.endsWith("/default.jsp")) {
            loginUrl.append("?useRedirects=true&RelayState=" + relayState);
        }
    } else {
        loginUrl.append("/login.jsp");
        if (StringUtils.isNotBlank(relayState)) {
            loginUrl.append("?os_destination=" + relayState);
        }
    }
    response.sendRedirect(loginUrl.toString());
%>>