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 release notes.

In this example, we use Jira Software 8.20.6 and Atlassian SSO App 4.2.1. The latest application version available when this document was written is 4.2.11.

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 Create App Integration.
   
   
   
   
2. On the Create a New Application Integration screen, choose the following and click on SAML 2.0
   
   
   
3. Add the information below on the Create SAML Integration page's General Settings and click on Next.

   • App name: 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.
     
     

4. Add the information below on the Configure SAML screen and click on Next.
   
   • Single sign-on URL: Add any URL but later, after configuring your Jira, edit to the Jira Assertion Consumer Service URL (will be similar to https://<jira>:8443/plugins/servlet/samlconsumer)

   • Audience URI (SP Entity ID): Add any URL but later, when configuring your Jira, edit to the Jira Assertion Consumer Service URL (will be similar to https://<jira>:8443)
   • Name ID format: EmailAddress; considering users would authenticate to Jira using their email address.
     • This must match 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. If using a different method, change accordingly.
     
     • This must match the username attribute in Jira's user directory, so you may need to change depending on the desired/used configuration.
       
       
5. On the Feedback screen, choose the options associated with your company and click on Finish.
   
   
   
   
6. The application is now created in Okta, and you are sent to the Sign On tab.
7. Under the Application Sign-On Settings, click on the View Setup Instructions to open a new window with the information 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 open and go to the next section to configure SAML SSO on Jira.
We will get back to the Okta administration to finish configuring the App later.

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 Authentication methods
   1. For SSO for Atlassian Server and Data Center App version lower than 4.2, click on SSO 2.0 under the Security section.
3. Give the integration a name.
4. Choose SAML single sign-on to configure the SAML SSO 2.0 settings on the Authentication method.
5. On the Single sign-on issuer attribute, use the value from Identity Provider Issuer from Okta's configuration from the previous section.
6. 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.
7. On the X.509 Certificate attribute, use the value from X.509 Certificate from Okta's configuration from the previous section.
8. On the Username mapping attribute, use ${NameID}.
   • This value is used based on the configuration made on Okta in the previous step. You may need to change it depending on your configuration.
9. Review your configuration to be similar to the sample image below.
   
   
   
10. Click on Save configuration and then on Save on the confirmation popup.

Everything is configured on Jira now.

Complete the Okta Application Configuration

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

1. On Okta, go to the Jira application and click on the integration created.
   
   
   
2. On General Setting, click on Edit on SAML Settings
   
3. Make the changes below on the SAML Settings screen and click on Next.
   

   • Single sign-on URL: use the value of the Assertion Consumer Service URL collected from Jira in the previous section.

   • Audience URI (SP Entity ID): use the value of Audience URL (Entity ID) collected from Jira in 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 in the regular way you have configured, either from the Internal User Directory or an external LDAP.

Therefore, we consider that users and groups are created in Okta to test this integration. For example, a user "oktauser" was added in Okta and Jira:

• Okta
  

• Jira
  

If used, associate the target group in Okta with the Jira application so that Okta can grant users access to it.

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

By doing this all users add to the specific group will have integration access to Jira.

To test the integration, go to Cog icon > System > Authentication methods > Test sign-in from the created integration

If everything is correctly configured, you will be redirected to Okta login, and you can test with a valid user as the SAML authentication flow.

Additional notes and configuration

Automatic redirect of unauthenticated users to the IdP

When a user accesses 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 feature 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; 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