• Products
  • Documentation
  • Resources

Configure SAML single sign-on with AD FS

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).

Before you begin

As an organization admin, there are a couple of things you need to do before you can configure SAML single sign-on with AD FS.

Prepare your Atlassian organization

You can configure SAML single sign-on after you’ve completed these steps:

  1. Verify one or more domains, to confirm you own those – see Verify a domain for your organization. When you verify a domain, all the Atlassian accounts that use email addresses from the verified domain become managed by your organization.

  2. Subscribe to Atlassian Access.

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 is been mis-configured.

    • 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.

  4. Because users won't be able to log in to your Atlassian products during the time it takes to configure SAML single sign-on, schedule a day and time for the changeover to SAML and alert your users in advance.

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

1. Add a SAML configuration

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

  1. Go to admin.atlassian.com. Select your organization if you have more than one.

  2. Select Security > SAML single sign-on.

  3. Select Add SAML configuration.

Add SAML configuration screen, includes Identity provider Entity ID, Identity provider SSO URL, and public x509 certificate

4. 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. Click Save Configuration.

Add SAML configuration screen, including your provider details and x509 certificate

2. 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.

3. Edit claim rules for the relying party trust

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

4. Test your SAML single sign-on integration

  1. Go to id.atlassian.com, enter the email address from a user in your Active Directory, and click Continue.

Atlassian login screen

2. You'll get redirected to your AD FS login page. Enter your credentials and click Sign in.

AD FS login page

If your configuration was successful, you land on start.atlassian.com.

Additional Help