Important Update Effective February 1, 2024!
Due to recent changes in Jira and Confluence, we've made the tough decision to discontinue the OpenID Connect (OIDC)/OAuth app and no longer provide new versions for the newest Jira/Confluence releases as of January 31, 2024.
This is due to some necessary components no longer shipping with Jira/Confluence, which would require some extensive rewrites of the OIDC App.
AD FS with LDAP User Directory
Goal
Configure SAML Single Sign-On for Atlassian Data Center and Server to work with AD FS and an existing LDAP based directory.
Prerequisites
- ADFS 2.0/2.1/3.0/2016
- Atlassian Data Center / Server application with a user directory of type LDAP
- Your Atlassian application must be accessible via HTTPS. (read more about it in the Atlassian documentation, i.e. for Jira or Confluence)
This is necessary because ADFS accepts only HTTPS-URLs for SAML endpoints.
Video Guide
The video below is an installation guide for setting up our SAML SSO app for Data Center / Server with ADFS (watch on YouTube).
Step-by-Step Setup Guide
Install the SAML SSO app
In your Atlassian product, open the in-product marketplace as described in the Atlassian documentation.
Search for "resolution saml" and click "Install" for SAML Single Sign On (SSO) by resolution Reichert Network Solutions GmbH.
After the installation is complete, click on Manage, then choose Configure.
Now, you are on the Add-on / app configuration page and the first step of the setup wizard will appear.
Configure SAML SSO app for Atlassian Data Center / Server
Add new Identity Provider (IdP)
Click on Add new IdP to start the wizard.
Adding a new IdP can also be done outside the wizard in the app configuration section Identity Providers
Select AD FS for the Identity Provider. For the Authentication Protocol, keep SAML2.
You may also change the name and add a description. The name needs to be unique.
Click on Next.
Retrieve SAML Metadata for ADFS
The next step enables you to retrieve the information ADFS needs to work with our SAML SSO app for Atlassian Data Center.
There are two ways to retrieve the metadata:
SAML Metadata via URL
If the server with ADFS has internet connection to your Atlassian instance, copy the SAML Metadata-URL shown on the screen.
If the server with ADFS has no internet connection, proceed with the next chapter, "SAML Metadata via XML file"
SAML Metadata via XML file
To get the metadata open the link in your browser instead and save the content as an XML file.
Click on Next already but you can now pause the SAML SSO setup for now and proceed with the next chapter configure the ADFS side:
Configure ADFS
For the remaining configuration of ADFS, please proceed with the steps described in the Configure ADFS tutorial linked here.
Import SAML IdP Metadata
Now that the ADFS configuration is complete, you can go ahead and resume configuration on the SAML SSO side.
We now need to import the metadata from ADFS.
You can choose from the following options in the Metadata Upload dropdown:
- Help me generate a metadata URL
- I have a metadata URL
- I have a metadata XML file
- I want to paste my metadata XML
- I don't have any metadata and want to enter the data manually
Option 1 is the easiest to use, provided that your Atlassian Data Center or Server instance has a connection to your ADFS server.
It will create the URL based on the hostname of your ADFS server. With Option 2 you could paste this URL manually.
Import via metadata URL
Provided the Atlassian instance does have access to ADFS, simply select the first option.
You only need to check the Accept all HTTPS certificates including self-signed certificates checkbox, if you are working in a test environment with self-signed certificates.
Leaving the Reload metadata automatically after a day option is highly recommended because it makes sure that the AD FS certificate rollover occurring each year is getting propagated automatically.
Without that, you'd need to refresh the metadata manually and set a reminder to not forget about this. However, it will require that your Atlassian instance has access to AD FS. Please make sure that it is not blocked by a firewall rule.
Click Import and Next to proceed.
Import via metadata XML file
With no access to ADFS, you can also export the metadata on ADFS and then load it with option 3 or paste its content with option 4.
Exporting can be done with a simple PowerShell script on ADFS. Just create a script file with extension ps1 and paste the following content:
# Export MetaData XML to current users desktop
$mUrl = (Get-ADFSEndpoint | where Protocol -eq "Federation Metadata").FullUrl.ToString()
$httpHelper = new-object System.Net.WebClient
$metadataAsString = $httpHelper.DownloadString($mUrl)
$httpHelper.DownloadFile($mUrl , "C:\Users\$($env:username)\Desktop\metadata.xml")Once the import of the metadata is complete, you can go ahead and configure the settings described in the following chapters.
Configure remaining SAML SSO app settings
User ID attribute and transformation
It's recommended to leave this option checked unless the username sent by AD FS doesn't match the username in your Atlassian instance.
You might need to adjust the AD FS Claims to send a different NameID/ attribute which matches your usernames.
User creation and update
Unless you want to assign groups to users after authentication or planning to use just-in-time provisioning, you should
leave this option unchecked. This can be configured later anytime.
Click Next to proceed.
Test configuration of SAML SSO app for Atlassian Data Center / Server
The last step when adding the ADFS IdP is a test that can be executed by clicking on the corresponding Start button.
Copy the link displayed and paste it into a new incognito/ private browsing window, and execute a login with AD FS
The status of the authentication process is permanently updated in the window.
If there is any error at this point you need help with, please refer to the troubleshooting guide, which will also help us, should you open a support ticket with us.
Of course the test window above will display a lot of information about the errors already, but requires some deeper knowledge of the SAML protocol.
Enable login redirection
The last step is to configure redirect options.
Selecting Enable SSO Redirect (1)will ensure that users are automatically getting redirected to be logged in via SAML, instead of via the login form as before the SSO setup.
If you leave it disabled for now, you can still test SSO for other users by providing them with the URL displayed in (2).
To login without SSO, use the link displayed in (3)
Save & Close to complete the setup and close the wizard. You are now ready to use LDAP with SAML SSO in your Atlassian Data Center application.
If Enable SSO Redirect is enabled, you can log in to your Atlassian Data Center / Server application manually by browsing to the URL that fits your Atlassian application as listed below.
Use this URL, if you need to log in a local user unknown to the ADFS or if there are any issues with Single Sign On.
- Jira: https://<baseurl>/login.jsp?nosso
- Confluence: https://<baseurl>/login.action?nosso
- Bitbucket: https://<baseurl>/login?nosso
- Bamboo 5: https://<baseurl>/userlogin!default.action?nosso
- Bamboo 6: https://<baseurl>/userlogin!doDefault.action?nosso