How to configure SAML authentication with Azure Active Directory on Jira Data Center

Related content

  • No related content found

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.

Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

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 authentication using SAML 2.0 or OIDC with the preferred Identity Provider (IdP) supporting these standards. Check SAML single sign-on for Atlassian Data Center applications for further details about the Atlassian SSO App.

This document highlights the steps to integrate Jira Software Data Center with Microsoft Azure Active Directory (Azure AD) 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 Azure AD or Jira configuration to your company needs. Hence, this describes a sample configuration to have it working.
For any Azure AD related issue or question, refer to Microsoft Azure support.


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:


You may want to check the screencast below with the walk-through to complete the configuration.



Install or update the Atlassian SSO App

SSO capabilities are provided in Jira Data Center as an Atlassian Marketplace App. Although you may have the Atlassian SSO App bundled with your Jira instance, 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.19.0, which is bundled with Atlassian SSO App 4.2.4, and the latest version available when this document was written is 4.2.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.



On we released version 4.2.0 of the Atlassian SSO App with the ability to configure multiple IdPs. With this version the SSO 2.0 label was changed to Authentication Methods, together with a few UI changes.

Version 4.2.0 is available for Jira 8.15.0 onward and, therefore, throughout this document we have different steps depending on your Jira version.


Gather initial data from Jira

In order to make the initial configuration on Azure AD, we need to collect two information from Jira, the , and the Audience URL (Entity ID).

  1. Access Jira as an administrator and go to Cog icon > System > Authentication methods.
  2. On the Authentication methods page, click on the Add configuration button.
  3. Under the option, choose SAML single sign-on.
  4. Scroll to the section named Give these URLs to your identity provider.
  5. Copy the values for and for .
  6. Click on the Cancel button as we won't complete any configuration on Jira now.
  1. Access Jira as an administrator and go to Cog icon > System > SSO 2.0.
  2. On the Configure how users log in page, choose SAML single sign-on as the option
  3. Scroll to the section named Give these URLs to your identity provider.
  4. Copy the values for and for .
  5. Navigate away from the current page as we won't complete any configuration on Jira now.


Create an application on Azure AD

Usually, your company will have a specific team managing the Azure Active Directory activities and you will interact with them, providing and receiving the necessary information to complete the configuration.

If you are working with your Azure AD team, provide them the information collected on the previous section. When they finish their configuration, these are the information they need to share with you and will be used on the next section:

  • The Login URL.
  • The Azure AD Identifier.
  • The SAML Signing Certificate on Base64 format.
    • The Atlassian SSO App supports signing only the SAML assertion.
  • The attribute in the SAML response to be used as the username mapping.
    • This is often the Name ID attribute.


In this section we will go through the steps needed to complete a simple application configuration on Azure AD.

  1. On Azure Active Directory admin center, go to All Services > Azure Active Directory > Enterprise Applications.
  2. Click on New Application.
  3. On the Browse Azure AD Gallery page, click on Create your own application.
  4. On the Create your own application popup, give the application a meaningful name, choose the appropriate option and click on Create.
  5. Under the Overview page of your application, click on Single sign-on and choose SAML as the SSO method.
  6. On the Set up Single Sign-On with SAML page, click on Edit on the Basic SAML Configuration section.
  7. On the Basic SAML Configuration popup, configure it as follows and click on Save.

    • Identifier (Entity ID) must be configured with the value from the attribute on Jira.

    • Reply URL (Assertion Consumer Service URL) must be configured with the value from the  attribute on Jira.
  8. Collect the following information to be used on the next section.
    • Download the Certificate (Base64).
    • The Login URL.
    • The Azure AD Identifier.
  9. Back to the Overview page of your application, go to Users and groups.
  10. On the Users and groups page, click on Add user/group.
  11. On the Add Assignment page choose None Selected under Users and groups.
  12. Choose a predefined group that will have access to the Jira application and then click on Assign.


Configure SAML on Jira


  1. Access Jira as an administrator and go to Cog icon > System > Authentication methods.
  2. On the Authentication methods page, click on the Add configuration button.
  3. On the Add new configuration screen, choose a Name for your configuration (i.e. Azure Active Directory) and select SAML single sign-on as the Authentication method.
  4. Under the SAML SSO settings, configure it as follows.
    • Single sign-on issuer is the value of the Microsoft Entra Identifier from the Azure AD application configuration.
    • Identity provider single sign-on URL is the value of the Login URL from the Azure AD application configuration.
    • X.509 Certificate is the value of the SAML Signing Certificate (Base64) from the Azure AD application configuration.
      • Make sure to use only the certificate string, discarding the BEGIN/END CERTIFICATE lines.
    • Username mapping is the attribute in the SAML response to be used as the username mapping, which must be configured as ${AttributeName}.
      • On our sample application the attribute is the NameID and it must be configured as ${NameID}.
    • On Login button text choose a meaningful text that will be presented to users as a login option.

  5. The configuration might look similar to the below images.

    Expand to see sample configuration...

  6. Click on Save configuration.
  1. Access Jira as an administrator and go to Cog icon > System > SSO 2.0.
  2. On the Authentication methods page, click on the Add configuration button.
  3. On the Configure how users log in screen select SAML single sign-on as the Authentication method.
  4. Under the SAML SSO 2.0 settings, configure it as follows.
    • Single sign-on issuer is the value of the Azure AD Identifier from the Azure AD application configuration.
    • Identity provider single sign-on URL is the value of the Login URL from the Azure AD application configuration.
    • X.509 Certificate is the value of the SAML Signing Certificate (Base64) from the Azure AD application configuration.
      • Make sure to use only the certificate string, discarding the BEGIN/END CERTIFICATE lines.
    • Username mapping is the attribute in the SAML response to be used as the username mapping, which must be configured as ${AttributeName}.
      • On our sample application the attribute is the NameID and it must be configured as ${NameID}.

  5. The configuration might look similar to the below image.

    Expand to see sample configuration...

  6. Click on Save configuration.



Test the SSO Integration


  1. Open an incognito window on your browser to ensure it won't use any of your session cookies.
  2. Access the Jira Base URL.
  3. Click on the Log In button on top bar.
  4. On the Log in to your account page, click on the button related to Azure AD.
  5. This will send you to the Microsoft authentication page.
  6. Authenticate with a valid user credential.
    1. The user must already exist on Jira with the proper Jira Software access.
    2. The user must have application access on Azure AD.
    3. The username on Jira must match with the value sent from Azure AD within the NameID or other configured attribute.
  1. As a Jira administrator, go to the SSO 2.0 page.
  2. At the bottom of the configuration page, there's a link to test the authentication under the Use SAML as secondary authentication option.
  3. Open this link in an incognito window and this should direct you to the Azure AD authentication page.
  4. Authenticate with a valid user credential.
    1. The user must already exist on Jira with the proper Jira Software access.
    2. The user must have application access on Azure AD.
    3. The username on Jira must match with the value sent from Azure AD within the NameID or other configured attribute.
  5. Once this authentication test works you may choose to setup SAML as the primary authentication method on Jira's SSO 2.0 configuration page.

Additional notes and configuration

Automatic redirect of unauthenticated users to the IdP

Before applying the workaround from this section, make sure the Load Balancer / Reverse Proxy health check is properly configured to send a GET /status.

If the health check is targeting only GET /, then nodes will be reported as unhealthy by the Load Balancer after applying the feature flag.

Refer to Load balancer configuration options for further details on configuring the health check.


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 to authenticate.
Also, the login form gadget may not be presented (since SAML is configured as the primary authentication method) and the user might 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 implemented, the suggested workaround makes the system dashboard private, 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


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.


See Also

Looking for similar guide for Confluence Data Center? See How to integrate Confluence Data Center with Azure for SAML 2.0 SSO.



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 4, 2024

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.