How to configure Jira Software Data Center for SAML 2.0 SSO with Okta

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform Notice: Data Center Only - This article only applies to Atlassian products on the data center platform.

Purpose

Jira Data Center is bundled with the SSO for Atlassian Server and Data Center App – we will refer to it simply as Atlassian SSO App in the remainder of this document.

With this App, Jira administrators can configure SSO using SAML 2.0 or OIDC with you preferred Identity Provider (IdP). Check SAML single sign-on for Atlassian Data Center applications for further details on supported IdPs and more information on the SSO App.

This document highlights the steps to integrate Jira Software Data Center with Okta for SSO using SAML 2.0.
Although it uses Jira Software as a reference, the concept is the same for Jira Service Management – therefore we will refer to Jira in the remainder of the document.
It might also be used as a reference to integrate Jira Data Center with other IdP solutions.

This document is not intended to be a full reference guide, since you may need to change Okta or Jira configuration to your Company needs. Hence, this describes a sample configuration to have it working.
For any Okta related issue or question, refer to Okta Help Center.


Atlassian products interface with a variety of technologies. Front-end solutions like Web Servers (eg Apache HTTP Server), load balancers, single sign-on solutions (SSO), SSL certificates, and LDAP repositories add functionality that is often critical to functioning of our products.

Atlassian will endeavor to provide documentation for integration with these 3rd party applications but does not provide support for 3rd party applications. We are unable to provide support when a failure in a 3rd party application occurs.

More information can be found in Atlassian Support Offerings.


Solution

Below is a summary of the Steps we will cover in this document:


Install or Update the Atlassian SSO App

SSO capabilities are provided in Jira Data Center as a Marketplace App. Although you may have this App bundled with Jira, it's best practice to update it to the latest version supported by your Jira release, ensuring you are protected from security bugs and is also running with the latest improvements.

Refer to the Atlassian SSO App version history for further details on supported Jira versions and for release notes.

On this example we are using Jira Software 8.13.3, which is bundled with Atlassian SSO App 4.1.1, and the latest version available when this document was written is 4.1.5.

Updating apps explains the options to update an App with Universal Plugin Manager (UPM).
If UPM is connected to the internet, it will advise you there's an update available and give you the option to update.


Create an Application in Okta

You will need to create a new application in Okta to make it available to users as Atlassian doesn't provide an Okta Application.

  1. As an Okta administrator, go to Applications and click on Add Application.


  2. On the Add Application screen, click on Create New App.

  3. On the Create a New Application Integration screen, choose the following and click on Create.
    • Platform: Web.
    • Sign on method: SAML 2.0.

  4. On the General Settings of the Create SAML Integration page, add the information as below and click on Next.
    • App name: it could be any name you would like to be presented to your users; we are using My Company Jira in this example.

    • Application logo: the logo you would like to be presented to your users; if you want to use any Atlassian logo, please refer to the Atlassian Design System site.

  5. On the Configure SAML screen, add the information as below and click on Next.
    • Single sign on URL: https://test.com; we are changing this later with the actual URL.
    • Audience URI (SP Entity ID): https://test.com; we are changing this later with the actual URL.
    • Name ID format: EmailAddress; considering users would authenticate to Jira using their email address.
      • This must match with the username attribute in Jira's user directory, so you may need to change depending on the desired/used configuration.
    • Application username: Email; considering users would authenticate to Jira using their email address.
      • This must match with the username attribute in Jira's user directory, so you may need to change depending on the desired/used configuration.

  6. On the Feedback screen, choose the options associated to your company and click on Finish.



  7. The application is now created in Okta and you are sent to the Sign On tab.
  8. Under the Sign On Settings, click on the View Setup Instructions to open a new window with information that will be used in the next section.



Now that the Okta integration App is created, keep the How to Configure SAML 2.0 for My Company Jira Application window opened and go to the next section to configure SAML SSO on Jira.
We will get back to the Okta administration later to finish configuring the App.



Configure SAML 2.0 on Jira

To configure SAML 2.0 on Jira using the Atlassian SSO App, you need to have Jira running with HTTPS. Refer to Running Jira applications over SSL or HTTPS if this isn't configured yet.


  1. Login to Jira as an administrator and go to Cog icon > System.
  2. Click on SSO 2.0 under the Security section.
    • With multiple IdPs support introduced on the App version 4.2.0, this label was changed to Authentication methods.
  3. On Authentication method choose SAML single sign-on to configure the SAML SSO 2.0 settings.
  4. On the Single sign-on issuer attribute, use the value from Identity Provider Issuer from Okta's configuration from the previous section.
  5. On the Identity provider single sign-on URL attribute, use the value from Identity Provider Single Sign-On URL from Okta's configuration from the previous section.
  6. On the X.509 Certificate attribute, use the value from X.509 Certificate from Okta's configuration from the previous section.
  7. On the Username mapping attribute, use ${NameID}.
    • This value is used based on the configuration made on Okta on the previous step. You may need to change it depending on your configuration.
  8. Review your configuration to be similar as the sample image below.

  9. On Login mode, keep the Use SAML as secondary authentication  choice for now so we can test it prior to making it the primary authentication method.
  10. Click on Save configuration and then on Save on the confirmation popup.
  11. You should see a confirmation popup saying the configuration was succesfully saved.


Everything is configured on Jira now.
For the next section, take notes of the  and  from the SAML SSO 2.0 settings page, since we will need them to complete the Okta configuration.


Complete the Okta Application Configuration

Back to Okta administration page, we still need to complete the configuration based on the information collected from Jira on the previous section.

  1. On Okta, go to the Jira application and, on the General tab, click on the Edit button of the SAML Settings section.

  2. On General Setting, click on Next without changing anything.
  3. On the SAML Settings screen, make the changes below and click on Next.
    • Single sign on URL: use the value of Assertion Consumer Service URL collected from Jira on the previous section.

    • Audience URI (SP Entity ID): use the value of Audience URL (Entity ID) collected from Jira on the previous section.

  4. On the Feedback screen, click on Finish without changing anything.


Test the SSO Integration

At this point, Jira is configured for SSO with Okta for authentication. User provisioning is still performed on the regular way you have configured, either from the Internal User Directory or from an external LDAP.

Therefore, to test this integration we consider that users and groups are created in Okta.

In this example, we have a group named jira-software-okta-group and with user oktauser001@user.com added to it.


The same user must exist in Jira, with the proper permissions to access the application.


If that's already configured, we need to associate the target group in Okta to the Jira application, so that Okta can grant users' access to it.

  1. On Okta administration, go to Directory > Groups and click on the target group.
  2. On the group administration page, click on Manage Apps.
  3. Click on the Assign button next to the Jira application and then click on Done.


To test if the integration is working, access <Jira-Base-URL>/plugins/servlet/external-login and authenticate to Okta as a test user.
This is the URL available in the Atlassian SSO App configuration page.


If everything is correctly configured, then accessing this link will follow the SAML authentication flow and send the user back to Jira.


After confirming everything is fine you may choose to make SAML the primary authentication option in the Atlassian SSO App configuration page.
Then any unauthenticated user trying to access Jira will be redirected to Okta to authenticate.


Additional notes and configuration

Automatic redirect of unauthenticated users to the IdP

When a user access the Jira Base URL, the browser is redirected to the system dashboard, which is a public dashboard by default, and the user won't be redirected to the IdP (Okta) to authenticate.
Also, the login form gadget isn't presented (since SAML is configured as the primary authentication method) and the user would be required to click on the Log In icon on the top bar.


There's a feature request to disable any public page in Jira – JRASERVER-65521 - Getting issue details... STATUS
While this feature isn't resolved, the suggested workaround makes the system dashboard private, automatically redirecting unauthenticated users to the IdP.

  • Login as an administrator and go to: <Jira Base URL>/secure/SiteDarkFeatures!default.jspa
  • In the Enable Dark Feature text field add public.access.disabled

Even with the above workaround, there will be other pages on which the redirect doesn't occur automatically, such as when accessing the URL for a private dashboard.

This is treated as a bug in JRASERVER-66554 - Getting issue details... STATUS and there's no workaround for it.


Secure administrator session (websudo)

Jira has secure administrator session enabled by default, meaning that they are required to re-authenticate when accessing an administration page as below.

This authentication challenge isn't sent to the IdP and, therefore, it will use the configured user directories.

There's a feature request to change it to use the IdP – JRASERVER-69311 - Getting issue details... STATUS .
While this isn't fixed, you may choose to disable it as described in Configuring secure administrator sessions.



Still having problems?

Contact Atlassian Support. We'll be happy to advise you. Please include as much detail as possible, where applicable:

  • Logs from the affected application (if applicable)
  • Screenshots of the error message (if they're not covered in logs)
  • Information about the steps you've taken previously




Last modified on Apr 5, 2021

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.