Configure SAML single sign-on with Active Directory Federation Services (AD FS)

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

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 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 site admin and 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, and navigate to Security > SAML single sign-on. Click Add SAML configuration to open this screen.

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

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

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

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

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

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

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

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

  5. Export your public key.

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

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

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

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

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

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

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

  6. Click Save Configuration.

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.

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

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

  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.

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

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

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

    2. Click Next.

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

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

    2. Click Next.

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

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

  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.

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

  2. Click Add Rule.

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

  4. Enter a name for Claim rule name.

    1. Copy the following into Custom Rule field.

      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);
    2. Click Finish.

  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.

    1. Copy the following into Custom Rule field.

      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");
    2. Click Finish.

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.

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

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


Last modified on Jul 26, 2019

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.