This setup guide describes how to complete the initial setup for SAML Single Sign On (SSO) for JIRA with ADFS, applicable for plugin version from 0.14.5. If you need any further support please feel free to contact us here.
Step1 Install the plugin | Step2 Setup the ADFS (A-E) | Step3 Configure the Plugin (A-B) | Step4 Test | Step5 Enable login redirection |
|---|
The video below is an installation guide for setting up SAML SSO for Confluence (URL: https://youtu.be/HB5blJt9VTE). As the steps are nearly identical with configuring the plugin for JIRA, it can be of great help for setting up the plugin.
Prerequisites
- ADFS 2.0/2.1/3.0
- JIRA must be accessible via HTTPS. See https://confluence.atlassian.com/jira064/running-jira-over-ssl-or-https-720411727.html for instructions.
This is necessary because ADFS accepts only HTTPS-URLs for SAML endpoints.
Step 1: Install the plugin
Click Add-ons under JIRA Administration on the top right corner of your JIRA interface. Then, you will be taken to Atlassian Marketplace. Search for SAML SSO and click on Free Trial to install.
After installation succeeded, click on Manage, then choose Configure. Now, you are on the plugin configuration page.
Step 2: Setup the ADFS
Substep A: Copy/Download the SAML Metadata URL
Substep A1:
- Copy the SAML Metadata-URL from your SAML Single Sign On config page.
Substep B: Start the Add Relying Party Trust Wizard
The rest of Step 2 will be completed in AD FS.
- Open the AD FS 2.0 Management Console and select Add Relying Party Trust to start the Add Relying Party Trust Wizard.
- Click the Start Button to start the wizard.
Substep C: Insert your SAML Metadata
Substep C1:
- Select Import data about the relying party published online or on a local network and paste in the SAML Meta-URL from JIRA in the Federation metadata address (host name or URL) field.
- Click Next.
Substep C2:
- Select Import data about the relying party from file and browse to your metadata.xml location with the Browse... button or fill in your location directly.
- Click Next.
Substep D: Finish the Add Relying Party Trust Wizard
- Fill the field Display name with a name of your choice.
- Click Next.
- Select I do not want to configure multi-factor authentication settings for this relying party trust at this time.
- Click Next.
- Select Permit all users to access this relying party.
- Click Next.
- Click Next.
- Check the Open the Edit Claim Rules dialog for this relying party trust then the wizard closes checkbox to open the Edit Claim Rules dialog after closing the wizard.
- Click Close to finish the Add Relying Party Trust Wizard.
Substep E: Add Name ID as Claim Rule
JIRA needs a Name ID (on the normal case) from the SAML Response to authenticate users. So we need to add a claim rule on ADFS, which add the Name ID in every SAML Response from ADFS.
- Navigate to ADFS → Trust Relationships → Relying Party Trusts on the left Navigation panel.
- Select your Relying Party Trust.
- Click on Edit Claim Rules... on the right Actions panel.
Otherwise, continue from below.
- Click the Add Rule... Button to open the Add Transform Claim Rule Wizard.
- Select Send LDAP Attributes as Claims in the Claim rule template drop-down list.
- Click Next.
- Fill the field Claim rule name with a name your choice.
- Select Active Directory in the Attribute store drop-down list.
- Select your appropriate LDAP Attribute in the first drop-down field from LDAP Attribute (Select or type to add more). In this example we are using the Windows login name attribute SAM-Account-Name as Name ID.
- Select Name ID in the first drop-down field from Outgoing Claim Type (Select or type to add more).
- Click Finish to complete the Add Transform Claim Rule Wizard.
- Check if your new rule has been added to the Edit Claim Rules dialog. Try again Step E if it has failed.
- Click Apply to save your settings.
- Click OK to finish.
Step 3: Configure the Plugin
To continue Step 3, please go back to the plugin configuration page opened in Step1.
Substep A: Load ADFS Metadata
The recommended way to setup the ADFS is to import ADFS Metadata. The Metadata URL from ADFS is https://<your-adfs>/federationmetadata/2007-06/federationmetadata.xml.
- Click the URL radio-button and paste the Metadata URL into the field below.
- Check Accept all if your IdP's https-certificate is not in your JIRA instance's trust store.
- Click on Load.
Substep B: Configure general JIRA groups in Advanced IdP Settings
If a user logs in using SAML, he will be added to the groups specified in the User Groups section. This applies to all users. The user is assigned to these groups in addition to the groups in the SAML-response's attribute.
The standard group in JIRA 6 is called jira-users.
The standard group in JIRA 7 is depending on which JIRA Version you are using:
| JIRA Version | Standard group |
|---|---|
| JIRA Core | jira-core-users |
| JIRA Software | jira-software-users |
| JIRA Service Desk | jira-servicedesk-users |
- Click on show Advanced IdP Settings, find User Group in the drop down menu.
- Click Save settings to store the configuration
Step 4: Test
In a separate browser, open the URL https://<your-JIRA>/plugins/servlet/samlsso.
You should be authenticated by your ADFS and redirected to the JIRA Dashboard.
Step 5: Enable login redirection
After testing, you can enable the login page redirection to finally activate the plugin. After checking the Enable SSO Redirect checkbox and clicking Save settings, requests to the JIRA login page should be redirected to the ADFS.
If Enable SSO Redirect is enabled, you can login to JIRA manually by browsing https://<your-JIRA>/login.jsp?nosso. Use this URL if you need to login a local user unknown to the ADFS or if there are any issues with Single Sign On.