SAML single sign-on

Security Assertion Markup Language (SAML) is an XML-based data format that makes it easier for your team to log in to Atlassian account using your organization's identity provider (IdP). In addition to maintaining the authentication of your users' Atlassian accounts, the most common use case allows users to sign in to multiple software applications using the same login details. This is referred to as single sign-on (SSO).

If you use G Suite to manage your users' accounts, we recommend you integrate with G Suite instead of setting up SAML.

This page

Before you begin

Before you configure SAML

From the Site Administration, go to Domains and complete the domain claim process for all email domains that you want to configure for SAML.

Make sure you have at least one Admin level account that isn't part of the domains you have verified. That way, you can still access your account in case any SAML settings are incorrect.

Here are other tasks that we recommend before you begin: 

  1. To ensure security and privacy of your authentication process, make sure both your Atlassian application and your IdP are using the HTTPS protocol to communicate with each other, and that the configured application base URL is the HTTPS one.
  2. SAML authentication requests are only valid for a limited time, so make sure the clock on your IdP server is synchronized with NTP. If you're using a SaaS IdP, your clock should already be synchronized.
  3. Users will need to have access to your Atlassian applications. You can add them from the User management  of your site administration or enable self-signup for your verified email domains.

Set up SAML

The following sections break down how to set up SAML. We've also include detailed instructions for the specific IdPs that we support: OneLogin, Okta, and Microsoft Azure.

If your IdP is Azure: See the Azure help page and the Atlassian Cloud app to set up SAML.

We don't officially support ADFS, so we recommend using Azure Active Directory instead.

If your IdP is OneLogin: See the OneLogin help page and the OneLogin app to set up SAML. Make sure you're logged in to see these pages.

If your IdP is Okta: See How to Configure SAML 2.0 for Atlassian Cloud? to set up SAML.

If your IdP is Ping: Not currently supported, but instructions to come soon.

1. Add the Atlassian application to your IdP

If you want your Atlassian application to provide SSO, you'll need to add it to your IdP. At the end of the setup process, your IdP will provide you with a set of data that you'll need to configure your Atlassian application.

The exact process varies depending on the IdP. We support OneLogin, Okta, and Azure, but you can use other IdPs that we don't support if you have another IdP. If you use an on-premise IdP, users are only be able to authenticate if they have access to the IdP (i.e. from your internal network or a VPN connection).

When you set up SAML, email addresses are case sensitive. Each Atlassian account email address must match the IdP email address.

If you're using an unsupported IdP: Make sure that your IdP can send email using the NameId attribute. When you add the Atlassian application, add the following SAML attribute mappings to your IdP:

SAML attribute name

What it should map to in your IdP

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

User's first name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname User's last name

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name or

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier  or

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

Internal Id for user that will not change

For IdP initiated SAML, enter your site's URL as the default relay state. Include https:// as part of your site's URL.

2. Copy details from your IdP to you Atlassian site

From your Atlassian site, go to  >  User management, and click SAML in the sidebar. Copy your IdP details to these fields on the SAML page of your Atlassian application, then click Save Configuration.

Field Description
Identity provider Entity ID

This value is the URL for the IdP where your application will accept authentication requests.

Identity provider SSO URL

This value defines the URL your users will be redirected to when logging in.

Public x509 Certificate

This value is sometimes referred to as a Signing Certificate and usually starts with '-----BEGIN CERTIFICATE-----'.

This certificate contains the public key we'll use to verify that your IdP has issued all received SAML authentication requests.

3. Copy details from your Atlassian site to your IdP

After adding your IdP details to the SAML page on your Atlassian site, you'll see new fields appear. Copy those fields over to your IdP. 

Click Save on your IdP when you've finished copying everything over. Go back to the SAML page of your Atlassian site, and click Save there too.

4. Test SAML for your Atlassian site

You test your SAML differently based on whether your site is using Atlassian account.

Possible login screen Testing instructions

If you see this screen when logging in, you have Atlassian account enabled for your site. Your SAML configuration applies as soon as you click Save from the Atlassian site. 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.
  2. From your site's login screen, sign in with an email address on one of your verified domains.
  3. Confirm you are signed in correctly and have all the expected access.

    If you experience a login error, go back to your original window, use Troubleshooting SAML below to make adjustments to your configuration, and test again in your incognito window.

    If you're unable to log in successfully, remove the configuration to ensure users can access your Atlassian site.

If you see this screen when logging in, you don't have Atlassian account enabled for your site. None of your users will be able to use SAML until your testing is complete. Use these steps to test and enable SAML:

  1. Open a new incognito window.
  2. From https://id.atlassian.com/login, sign in with an email address on one of your verified domains to confirm that you're able to log in.
    You'll know things are working correctly when you're taken to an Atlassian account profile screen. If you have problems authenticating, return to your original tab and make adjustments.

  3. Click Single sign-on from the Site administration of your Atlassian site.
  4. Toggle the Enable single sign-on switch to opt-in to the new Atlassian account login.
  5. Open a new private-browsing window, and go to <yoursite>.atlassian.net to confirm you can log in using SAML.

Troubleshooting SAML

If you experience errors shown by your IdP, use the support and tools that your IdP provides, rather than the Atlassian support.

If you're unable to access your site because of a SAML configuration:

  1. Go to https://id.atlassian.com/login?saml=false and log in with your Atlassian account username and password. Then, go into your site administration to fix or disable SAML for the rest of their users.

  2. If you're still having trouble, delete the SAML configuration to go back to password authentication with Atlassian account.

    If you delete the SAML configuration, you can invalidate all your users' passwords in the password policy screen, which will prompt users to go through the password reset process.

  3. If users are still having issues authenticating to the instance, turn off Single sign-on for Atlassian account. All end-users who successfully went through migration will receive an email to reset their password. This final process takes you right back to where you were originally. This is a last resort, as we'd like to help resolve any issues before it comes to this point. 

For support tickets being raised, please include the SAMLRequest and SAMLResponse payloads, obtained from the SAML Tracer Firefox add-on. This helps us more quickly identify potential causes of issues.

 

  If you're trying to troubleshoot an error, refer to our table of possible error messages and screens.

Errors

Possible issues

A plain error screen with no Atlassian branding.

You might have network connectivity issues with your IdP. Try refreshing your page to see if solves the issue.

An error screen for your IdP.

You might have an issue with your IdP configuration, e.g. a user may not be able to access the Atlassian application from the IdP. Raise a ticket with your IdP to fix the issue.

"Your email address has changed at your Identity Provider. Ask your administrator to make a corresponding change on your Atlassian products."

Known issue with the SAML Beta. You'll soon be able to change the email addresses of your managed accounts from User management.

"We weren't able to log you in, but trying again will probably work."

SAML configuration was disabled for the user during the login process. Verify the SAML configuration and try again.

  • We were expecting you to arrive with a different Identity Provider Entity Id. Ask your administrator to check the Atlassian configuration of SAML. You had xxx; but we were expecting xxx.

  • "Invalid issuer in the Assertion/Response"

The IdP Entity Id in the SAML configuration under your Site administration may be incorrect. Verify that you're using the correct Entity Id and try again.

"xxx is not a valid audience for this Response"

The Service Provider Entity Id in the IdP SAML configuration may be incorrect. Verify that you're using the correct Entity Id and try again.

"The response was received at xxx instead of xxx"

The Service Provider Assertion Consumer Service URL in the IdP SAML configuration may be incorrect. Verify that you're using the correct URL and try again.

"The authenticated email address we were expecting was 'xxx', but we received 'xxx'. Please ensure they match exactly, including case sensitivity. Contact your administrator to change your email to match."

The user tried to log in to the IdP with an email address different from their Atlassian account email address. Verify that the user is logging in with the correct email address. Email addresses are also case sensitive.

  • "We were expecting an email address as the Name Id, but we got xxx. Please ask your administrator to check that Name Id is mapped to email address."

  • "We were expecting an email address as the Name Id, but didn't get one. Please ask your administrator to check that Name Id is mapped to email address."

  • "We were expecting a user ID, but didn't get one. Please ask your administrator to check that user ID is populated in the response. See the configuration and troubleshooting guide below."

  • "Unsupported SAML Version."

  • "Missing ID attribute on SAML Response."

  • "SAML Response must contain 1 Assertion."

  • "Invalid SAML Response. Not match the saml-schema-protocol-2.0.xsd"

  • "Invalid decrypted SAML Response. Not match the saml-schema-protocol-2.0.xsd"

  • "Signature validation failed. SAML Response rejected"

  • "No Signature found. SAML Response rejected"

  • "The Assertion of the Response is not signed and the SP requires it"

  • "The attributes have expired, based on the SessionNotOnOrAfter of the AttributeStatement of this Response"

  • "There is an EncryptedAttribute in the Response and this SP not support them"

  • "Timing issues (please check your clock settings)"

  • "The Response has an InResponseTo attribute: xxx while no InResponseTo was expected"

  • "The InResponseTo of the Response: xxx does not match the ID of the AuthNRequest sent by the SP: xxx"

You're most likely using an unsupported IdP. Verify your IdP configuration by making sure you've done the following:

  1. The IdP can return email as the NameId.

  2. A user Id is mapped as a SAML attribute.

  3. The SAML responses are signed and not encrypted.

  4. The IdP's time is synchronised with NTP.

SAML Frequently Asked Questions

Can I get SAML for domains that I cannot verify?

No. To keep users secure, you are only able to apply a SAML policy to an email address you can verify that you own.  

What happens if I have a password policy?

SAML supersedes any password policy, meaning your policy is essentially "skipped" in the login process. When setting a password at id.atlassian.com (for use with API integrations) the policy will apply.

Do users with SAML accounts need to verify their emails?

A user with an Atlassian account needs to verify their email address, but SAML-associated accounts on Atlassian accounts are implicitly verified.  

Are there any Atlassian cloud products that SAML isn't available for yet?

SAML isn't available yet for Bitbucket Cloud or HipChat, but we have plans to gradually roll out SAML to these products. If your Atlassian site isn't using Atlassian accounts yet, we recommend that you set up your site to start using Atlassian account, which will eventually allow your users to log in to all cloud products with one account.

How does API authentication work?

If you have APIs set up:

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport