Configure SAML 2.0 for Jira Align using Azure AD

[#1]

Azure Active Directory is a popular SAML 2.0 service. The following is an example of how we have tested and configured Azure with Jira Align. Please review the following example and adjust as needed for your organization's security policies and practices. 

Azure

1. Sign into Azure and click on Azure Active Directory.

2. Select Enterprise Applications from Manage in the left column. 

3. Click on New application.

4. Select Non-gallery application.

5. Name the application something relevant to your organization and/or the application itself and click Add. In this case, we've named it JiraAlign.

Note: Any spaces in the name will cause issues with the Login URL later so it's best to just avoid them.

6. Under the Getting Started section, click on 1. Assign users and groups.

7. Click Add user and add Users as needed. You need at least one User to test SSO and you can go back and add more later if you want.

8. On the Add Assignment screen, you can select the users you want, click Select and Assign.

9. The user(s)/group(s) should show up on the Users and groups pane now.

10. Click on Single sign-on and SAML.

11. In Section 1: Basic SAML Configuration, edit the Identifier (Entity ID) and  Reply URL (Assertion Consumer Service URL) to both be the Jira Align instance:

https://instance.agilecraft.com or https://instance.jiraalign.com 

Click Save.

Alternatively, you can upload the metadata file by copying the Show Jira Align Saml 2.0 Service Provider metadata from Jira Align (Administrator > Platform > Security) and save as an XML file. 

12. In Section 3: SAML Signing Certificate, edit and change the Signing Option to Sign SAML response and assertion. Click Save.

13. Also, in Section 3: SAML Signing Certificate, click Download next to Federation Metadata XML to use in a later step.

14. Please note that Azure has made some recent changes surrounding Logout URL. Please use the provided URL below and also read through the "Sign Out URL" section at the end of this article. 

Logout URL: https://login.microsoftonline.com/common/wsfederation?wa=wsignout1.0

15. In the left hand menu under Manage, click Properties and copy the User Access URL for use in a later step. User Access URL will start with https://myapps.microsoft.com/signin. 

Jira Align

16. Sign into Jira Align and click Administration > Platform > Security.

17. Click Add SAML Provider. 

18. Paste in the SAML 2.0 Metadata from Azure (Step 13 from earlier).

19. Click Save & Close.

20. Set Enable SSO to Yes.

21. Click Save Settings.

Testing

22. Open up an incognito window in your browser and navigate to the User Access URL from Azure (Step 15 from earlier).

---

Additional Notes

• The user account you are testing from Azure SAML 2.0 must be also configured on the Jira Align side.
• User accounts on the Jira Align side can be created using the following methods:
  • API 1.0
  • Excel Import
  • Manually created
  • Users automatically integrated from Jira (the user must be assigned to an integrated issue)

---

Sign Out URL / Logout URL

• Azure made a recent change to the default Sign Out URL from the WS-Federation Sign-Out URL to the Single Sign-Out URL.  
• Jira Align currently does not support the Single Sign-Out URL method:   https://login.microsoftonline.com/<tenant-id>/saml2 
• Jira Align supports the WS-Federation Sign-Out URL: https://login.microsoftonline.com/common/wsfederation?wa=wsignout1.0
• Please see this article for more info.
• Sign-Out Overview (WS-Federation) - Reference - Read More
  Single Sign-out (aka Global SLO) is the simultaneous termination of all user sessions for the browser that initiated the sign-out. Closing all user sessions prevents unauthorized users from gaining access to resources at the Resource Partner.

---

Disable Manual Sign In

• Once you are confident that there are no known issues with SSO, you can go back to Platform Settings from earlier and set Disable Manual Sign In to Yes. 

You'll need to open a ticket with Jira Align to regain access if you get locked out while Disable Manual Sign In is turned on. 

• After you have set Disable Manual Sign In, you'll be able to fill out the following fields:
  • Sign In URL (use the URL from step 15)
  • Sign Out URL (use the URL from step 14)

If for some reason your Sign In or Sign Out URL contain encoded characters (Example: %20 for space), you'll need to replace that with the non-encoded equivalent.

---

Default Roles

To change the default roles assigned to new users, please navigate in Jira Align to Admin > Connectors > Jira Settings > Jira Setup. 

Scroll all the way to the bottom and review the Default System Role for New User(s) and Default Team Role for New User(s).

Also please review this article for more specifics on System Roles vs Team Roles.

[Tim Keyes]

Awesome article @James McCulley!

Great work!

[Karalee Kikiros]

Hi, why have the image stores gone to imgur? Enterprise customers are going to have a problem going forward with community.atlassian.com if this is preferred image as enterprises (like mine) block imgur. Many thx

[Tim Keyes]

Hi Karalee,

Do you know of any image hosting sites that your network does not block?  

Thank you!
Tim

[Karalee Kikiros]

Hi Tim, I emailed you directly to chat further. 

[James McCulley]

Karalee,

I have made a change to where the images are hosted.  Can you confirm you can see them now?

Thanks!

James

[Karalee Kikiros]

I can @James McCulley, thanks! Are the other being pages updated as well or will they be updated on an ad-hoc basis? e.g. https://community.atlassian.com/t5/Jira-Align-articles/Domain-Migration-agilecraft-com-to-jiraalign-com-Impacts-on/ba-p/1451258 still has imgur. I can @ mention you/Tim if/when I find another?

[Tim Keyes]

Hi Karalee,

I probably have about 12 articles with images hosted in Imigur.  I will move them over to hosting on the community's site over the next week or two.

Cheers!
Tim

[Karalee Kikiros]

Hi @James McCulley a quick note to let you know that this article was so helpful for us today! Your note about the User Access URL was spot on - it didn't work so I piped up with your tip about no spaces when setting up... and it fixed it

[Heidi Hendry]

Hi @James McCulley 
thank you for this article... very informative.
Is there a setting in here that needs to be set to support URL redirection?

So I share a JA URL with an end-user and then they click that link.
If URL redirection IS enabled, then that link will take them to the SSO login and then to the link.
If URL redirection IS NOT enabled, then that link will take them to the SSO login and then to their last logged-in screen.

thank you

[James McCulley]

@Heidi Hendry Thank you and great question. From working with Azure Support over a number of hours, it was determined that Azure Active Directory doesn't support Jira Align's URL redirection functionality.

[Helge Heupel]

Hi @James McCulley 

Thank you very much for this article.

I just wanted to circle back one important addition that solved the sign-out problem that I was encountering so that others would have the solution readily available:

Implementing "14. In Section 4: Set up <name>, copy the Logout URL", I ran into the problem that both my Azure Login URL and Logout URL are identical. Therefore, the logout did not work properly. 

For step 14 to work, it required me within the Azure Basic SAML Configuration to add the logout url you have kindly provided:

https://login.microsoftonline.com/common/wsfederation?wa=wsignout1.0

Instead of the Logout URL from Azure, I obviously added your url as the sign-out URL in Jira Align under Platform Settings Security as well:

Now, everything works.

Best wishes,

Helge

[Syed Parveez Pasha]

Thanks for sharing this @Helge Heupel :) 

[James McCulley]

@Helge Heupel ,

Thanks for your detailed comment. In my testing, I have not had to add that configuration change on the Azure side. Can you tell me what behavior you were seeing before that change you made? 

Thanks,

James