• Documentation

Configure SAML single sign-on with AD FS

You can now find SAML single sign-on in the same place you manage your identity provider. To find it, go to Security > Identity providers. About identity providers

Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization data between an identity provider and a service (such as Confluence Cloud).

This page provides the steps to configure SAML single sign-on with Active Directory Federation Services (AD FS).

Who can do this?
Role: Organization admin
Plan: Atlassian Guard Standard

Before you begin

Here's what you need to do before you set up SAML single sign-on with AD FS.

Subscribe to Atlassian Guard Standard from your organization. Understand Atlassian Guard

Make sure you're an admin for an Atlassian organization.

Verify one or more of your domains in your organization. Learn about Domain verification

Add an identity provider directory to your organization. Learn how to Add an identity provider

Link verified domains to your identity provider directory. Learn how to link domains

Let your users know they won't be able to log in to Atlassian products while you're doing the setup

Create an authentication policy to test your SAML configuration
. After you set up SAML, you can enable single sign-on for this authentication policy.

Prepare your Atlassian organization

We also recommend the following:

  1. Check that your Atlassian products and AD FS use the HTTPS protocol to communicate with each other, and that the configured product base URL is the HTTPS one.

  2. Because SAML authentication requests are only valid for a limited time, make sure the clock on your identity provider server is synchronized using NTP.

  3. Create an Atlassian account that you can use to access your organization if SAML has been misconfigured.

    • Use an email address from a domain you haven’t verified so that the account won't redirect to SAML single sign-on when you log in.

    • Give the user organization admin access. You can remove admin access when you are satisfied that SAML single sign-on is working as expected.

Prepare your Microsoft Windows Server

  1. Install and run your Active Directory.

  2. Install Microsoft Active Directory Federation Services.

  3. Connect Microsoft Active Directory Federation Services to your Active Directory.

Set up SAML single sign-on

This configuration requires AD FS 2.0+

We most recently tested on Windows Server 2016 Datacenter and AD FS 4.0

Add a SAML configuration

Complete these steps to add a SAML configuration from your Atlassian organization for your users.

  1. From your organization at admin.atlassian.com, select Security > Identity providers.

  2. Select your AD FS Directory.

  3. Select Set up SAML single sign-on.

The ability to configure SAML single sign-on for Jira Service Management customers is available for people in an early access program. This feature will be available to everyone soon.

Follow these steps if you want to add a SAML configuration from your Jira Service Management site for your portal-only customer.

  1. From your organization at admin.atlassian.com, select Products.

  2. Under Sites and products, select the site you want to configure the SAML SSO for.

  3. Under Jira Service Management, select Portal-only customers.

  4. Select More > Identity providers.

  5. Select your AD FS Directory.

  6. Select Set up SAML single sign-on.

Add SAML details

  1. From the AD FS management tool, right click AD FS from left panel and click Edit Federation Service Properties.

List of actions when you right click AD FS from left panel, including highlighted Edit Federation Service Propertie

5. From the Federation Service Properties dialog, copy the value under Federation Service identifier.

a. Go back to the Add SAML configuration screen on admin.atlassian.com.

b. Paste the value in the Identity provider Entity ID field.

Federation Service Properties screen on the General tab. Includes Federation Service display name, name, and identifier

6. Return to the AD FS management tool, and select AD FS > Service > Endpoints in the left panel.

a. Under Token Issuance, search for and copy the URL path with a Type of SAML 2.0/WS-Federation.

A screen of all the endpoints under the AD FS service directory, including the SAML 2.0/WS-Federation type

b. Go back to the Add SAML configuration screen on admin.atlassian.com.

c. Paste the path, prefixing it with your server URL (e.g. https://<myadfsserver.com>/adfs/ls/) into the Identity provider SSO URL field.

7. Export your public key.

a. From the AD FS management tool, select AD FS > Service > Certificates from right panel. Right click the certificate under the Token-signing section and click View Certificate.

AD FS service certificates, with Token-signing section highlighted, and View Certificate selected from right-click options

b. From the Certificate dialog, switch to the Details tab and click Copy to File.

Details tab in the Certificate screen showing a table of fields and their values

c. From the Certificate Export Wizard that opens, click Next.

Welcome screen of the certificate export wizard, with explanation about the wizard

d. Select Base-64 encoded X.509 (.CER) for the format and click Next.

Export file format screen with a list of available file formats for exporting certificates

e. From File name, specify the path to where the exported certificate should save along with its filename and click Next.

File to export screen with the file name and path you want to export, with a Browse button

f. Review the settings for the exported certificate and click Finish.

Completing the certificate export wizard page with the settings you specified and Finish and Cancel buttons

g. Open the exported certificated file and copy the certificate key. Go back to the Add SAML configuration screen on admin.atlassian.com and paste the value in the Public x509 certificate field.

Screenshot of base64-cert in Notepad

8. Select Save Configuration.

Create a new relying party trust

Complete the steps in this section from the AD FS management tool.

  1. From the AD FS management tool, expand AD FS from left panel, select Relying Party Trusts and click Add Relying Party Trust from right panel.

AD FS management tool, Relying Party Trusts window, with highlighting of Add Relying Party Trust from right panel

2. From the Add Relying Party Trust Wizard, select Claim Aware and click Start.

Add relying party trust wizard welcome screen. Select claims aware or non claims aware

3. Select Enter data about relying party manually and click Next.

Add relying party trust wizard, select data source step

4. Enter a Display name for your relying party and click Next. This name will appear under your Relying Party Trusts list in the AD FS management tool.

Add relying party trust wizard, specify display name step

5. From the Configure Certificate step, click Next. You don’t need to encrypt any of the tokens as part of the setup.

Add relying party trust wizard, configure certificate step

6. Select Enable support for the SAML 2.0 WebSSO protocol.

a. From your SAML single sign-on page at admin.atlassian.com, copy the SP Assertion Consumer Service URL and paste the value into the Relying party SAML 2.0 SSO Service URL field in the AD FS wizard.

b. Click Next.

Add relying party trust wizard, configure URL step

7. From your SAML single sign-on page at admin.atlassian.com, copy the SP entity ID value.

a. Paste the value into Relying party trust identifier field in the AD FS wizard and click Add.

b. Click Next.

Add relying party trust wizard, configure identifiers step

8. From the access control policy lists, select Permit everyone and click Next.

Add relying party trust wizard, choose access control policy step

9. From the Ready to Add Trust step, review your settings and click Next.

Add relying party trust wizard, ready to add trust step

10. Click Close to complete the wizard.

The steps in this section map how AD FS sends claims to your Atlassian organization. This mapping requires two rules that you add to AD FS. The first one maps these AD fields to SAML fields: Email, Given Name and Surname. The second rule maps the Name Identifier.

If you’re using Microsoft Azure, refer to this tutorial, and read point 14 within the ‘Configure Azure AD with Atlassian Cloud SSO’ section. Use the same email address to log in (from the AD) as mentioned in the mapping.

  1. From the AD FS management tool, right click the relying party trust that you recently added and click Edit Claim Issuance Policy.

AD FS management tool, relying party trust selected, then Edit Claim Issuance Policy selected

2. Click Add Rule.

Edit Claim Issuance Policy for Atlassian cloud screen, Issuance Transform Rules tab

3. From the Claim rule template dropdown, select Sending Claims Using a Custom Rule and click Next.

Add transform claim rule wizard, select rule template tab

4. Enter a name for Claim rule name.

a. Copy the following into Custom Rule field.

1 2 c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"), query = ";objectSID,mail,givenName,sn;{0}", param = c.Value);

b. Click Finish.

Add transform claim rule wizard, select rule template tab, configure claim rule stepep

5. Click Add Rule again.

6. From the Claim rule template dropdown, select Sending Claims Using a Custom Rule and click Next.

7. Enter a name for Claim rule name.
a. Copy the following into Custom Rule field.

1 2 c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"] => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");

b. Click Finish.

Add transform claim rule wizard, select rule template tab, choose rule type step

Test your SAML single sign-on integration

You have two ways to test based on whether you have authentication policies.

Test SAML single sign-on with Authentication policies

Authentication policies give you the flexibility to configure multiple security levels for different user sets within your organization. Authentication policies also reduce risk by allowing you to test different single sign-on configurations on subsets of users before rolling them out to your whole company.

You may want to:

  • Test single sign-on (SSO) or two-step verification on a smaller, select group of users to ensure it is setup correctly before rolling it out across your organization.

  • Troubleshoot your SSO policy by setting up a different policy for different admin accounts so you can log in and troubleshoot your SSO policy or identity provider integration.

To test the settings for authentication, you'll need to configure and enforce SAML single sign-on. The following section provides instructions on how to do it.

Test SAML single sign-on configuration without Authentication policies

Your SAML configuration applies as soon as you select Save on your Atlassian organization. Because we don't log out your users, use these steps to test SAML configuration while still making adjustments:

  1. Open a new incognito window in your browser.

  2. Log in with an email address from one of your verified domains.

Confirm you're signed in. If you experience a login error, go to the Troubleshooting SAML single sign-on to adjust your configuration and test again in your incognito window.

If you can't log in successfully, delete the configuration so users can access Atlassian products.

 

Still need help?

The Atlassian Community is here for you.