SAML single sign-on

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 parties, in particular an identity provider and a service provider (such as Confluence Cloud).

SAML for single sign-on (SSO) allows your users to authenticate through your company's identity provider when they log in to Atlassian Cloud products. SSO allows a user to authenticate once and then access multiple products during their session, without needing to authenticate with each of those apps. Note that SSO will only apply to your managed Atlassian accounts, that is accounts that have email addresses from your verified domains.

Once your users can log in using SAML single sign-on, they'll still need to be given access to your Atlassian products. See Manage application access for how to do that.

You need to have already subscribed to Atlassian's Identity Manager before you can set up SAML single sign-on for your managed users. Identity Manager is free to try for a limited time – Identity Manager's Early Access Program.

Note that if you manage users for an Atlassian Cloud site with G Suite, you'll need to use the SSO feature provided by G Suite instead.


Before you begin

We recommend that you check the following before you begin: 

  1. Both your Atlassian product and your identity provider should use the HTTPS protocol to communicate with each other, and that the configured product base URL is the HTTPS one.
  2. SAML authentication requests are only valid for a limited time, so make sure the clock on your identity provider server is synchronized using NTP. If you're using a SaaS identity provider, your clock should already be synchronized.
  3. Before configuring SAML single sign-on, create an Atlassian account that you can use to access your organization even if SAML has been mis-configured. This account:

    • must not use an email address from a domain you have verified for this organization. This ensures that the account will not redirect to SAML single sign-on when you log in.
    • must be given both site admin and organization admin access.

    Consider this account as temporary: you'll be able to remove admin access from it when you are satisfied that SAML single sign-on is working as expected for your users.


Set up SAML single sign-on

This section describes how to set up SAML single sign-on.

  • You need to have already subscribed to Identity Manager before you can set up SAML single sign-on for your managed users. See Security with Identity Manager for details about how to do that.
  • Note that during the time it takes to configure SAML single sign-on, users won't be able to log in to your Atlassian Cloud products. Consider scheduling a day and time for the changeover to SAML, and alerting your users in advance.

Supported identity providers

If your identity provider is in the following table, then follow the link to their instructions for setting up SAML single sign-on. If you can't see your identity provider here, use the instructions provided in the 'Unsupported identity providers' section below.

Identity provider Set up instructions
Azure

See:

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

Bitium Configuring SAML for Atlassian Cloud
Centrify Centrify's help page
Okta How to Configure SAML 2.0 for Atlassian Cloud
OneLogin

See:

You'll need to be logged in to OneLogin to see those pages.

Ping Not currently supported, but instructions to come soon.


Unsupported identity providers

Follow the steps in this section if your identity provider is not listed in the table above.

1. Add the Atlassian product to your identity provider

In this step you tell your identity provider which Atlassian products will use SAML single sign-on.

If you use an on-premise identity provider, your users will only be able to authenticate if they have access to the identity provider (for example, from your internal network or a VPN connection).

Make sure that your identity provider can send email using the NameId attribute. When you add the Atlassian product, add the following SAML attribute mappings to your identity provider:

SAML attribute name

What it should map to in your identity provider

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/upn

Internal Id for user that will not change

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

2. Copy details from your identity provider to your Atlassian organization

  1. Go to  Application picker Site administration and choose either Organization or  Security, under 'Organizations & Security'.
  2. Choose SAML single sign-on, on the left.
  3. Choose Add SAML configuration and then copy your identity provider details to these fields:

    Field Description
    Identity provider Entity ID

    This value is the URL for the identity provider where your product 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 begins with '-----BEGIN CERTIFICATE-----'.

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

  4. Click Save configuration.


3. Copy details from your Atlassian organization to your identity provider

After adding your identity provider details to the 'SAML single sign-on' page for your Atlassian organization, you'll see new fields and values appear. Copy those values over to your identity provider. 

Click Save on your identity provider when you've finished copying everything over.

4. Test SAML single sign-on for your Atlassian organization

Your SAML configuration applies as soon as you click 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.
  3. Confirm you are signed in correctly and have all the expected access.

    If you experience a login error, use the Troubleshooting SAML single sign-on section 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 products.

SAML single sign-on with two-step verification and password policy

When SAML single sign-on is configured, users won't be subject to Atlassian password policy and two-step verification if those are configured for your organization. This means that any password policy and two-step verification is essentially "skipped" during the login process. 

We recommend that you use your identity provider's equivalent offering instead.

Update your SAML configuration

We've made a change to how SAML single sign-on works at our end that requires you to update your SAML single sign-on configuration. You'll need to complete the steps described below by Friday April 6th, 2018 – if you don't make these changes by then, your SAML single sign-on configuration may stop working.

How do I update my SAML single sign-on configuration?

Update your SAML single sign-on configuration by completing the steps described below – you need to do this by Friday April 6th, 2018.

This should be a quick change to make, but while you're doing that your users won't be able to log in (users already logged in won't be affected). Consider scheduling a time to make this change, and alerting your users.

  1. Go to  Application picker Site administration and choose either Organization or  Security, under 'Organizations & Security'.
  2. Choose SAML single sign-on, on the left.
  3. Copy the new SP Entity ID and SP Assertion Consumer Service URL that we've provided on your SAML single sign-on settings page. 
  4. Use the specific instructions here if you're using one of the following providers (otherwise, save those new values in your identity provider's configuration settings):
Azure...

Microsoft Azure AD

Go to your Atlassian Cloud app in Azure AD, and click on Single sign-on, under 'Manage'.

Next, update the settings as described in this table, and don't forget to save your changes:

Screenshot Field name Value
1. Identifier Paste the value for SP Entity ID that you copied from the Atlassian SAML single sign-on screen.
2. Reply URL Paste the value for SP Assertion Consumer Service URL that you copied from the Atlassian SAML single sign-on screen.
3. Sign on URL Enter your Atlassian Cloud instance URL (it has the pattern  https://example.atlassian.net )
4. User identifier Don't change the existing value for this attribute.
5. SAML token attributes Remove any attributes other than givenname and surname, as shown in the screenshot below.


Now, return to your Atlassian SAML single sign-on settings page and click the Yes, update my configuration button.


Screenshot of the Azure AD settings page:

Okta...

Okta

Go to the Advanced Sign-on Settings for your Okta app.

Next, update the settings as described in this table, and don't forget to save your changes:

Field name Value
Unique ID

Copy the string at the end of the SP Entity ID from the Atlassian SAML single sign-on screen (it's the same for the SP Assertion Consumer Service URL too), as shown here:

Paste that string into the Okta Unique ID field.


The Jira and Confluence Base URLs remain the same.

Now, return to your Atlassian SAML single sign-on settings page and click the Yes, update my configuration button.


Screenshot of the Advanced Sign-on Settings for your Okta app:

Onelogin...

Onelogin

First up, you need to set up a new connector app – follow the Onelogin instructions to do this.

Next, in the Configuration for the connector app, update the settings as described in this table, and don't forget to save your changes:

Field name Value
Atlassian SAML ID

Copy the string at the end of the SP Entity ID from the Atlassian SAML single sign-on screen (it's the same for the SP Assertion Consumer Service URL too), as shown here:

Paste that string into the Onelogin Atlassian SAML ID field.


The Atlassian Site URL remains the same.

Now, return to your Atlassian SAML single sign-on settings page and click the Yes, update my configuration button.

When you've confirmed that the new SAML single sign-on configuration is working as expected, you can remove the old Onelogin app.


Screenshot of the Onelogin connector app Configuration page:

Bitium...

Bitium

Go to the Single Sign-On configuration page in Bitium.

Next, update the settings as described in this table, and don't forget to save your changes:

Screenshot Field name Value
1. Entity ID Paste the value for SP Entity ID from the Atlassian SAML single sign-on screen.
2. ACS URL Paste the value for SP Assertion Consumer Service URL from the Atlassian SAML single sign-on screen.


Now, return to your Atlassian SAML single sign-on settings page and click the Yes, update my configuration button.


Screenshot of the Bitium settings page:

Centrify...

Centrify

Go to your Centrify admin area, and click Apps > Application Settings.

Update the settings as described in this table, and don't forget to save your changes:

Screenshot Field name Value
1. SP Entity ID Paste the value for SP Entity ID that you copied from the Atlassian SAML single sign-on screen.
2. SP Assertion Consumer Service URL Paste the value for SP Assertion Consumer Service URL that you copied from the Atlassian SAML single sign-on screen.


Now, return to your Atlassian SAML single sign-on settings page and click the Yes, update my configuration button.


Screenshot of the Centrify settings page:


What should I do if I'm having issues after updating my SAML single sign-on configuration?

If Atlassian has advised you to update your SAML configuration by Friday April 6th 2018, and you're having issues after having tried to do that, follow these steps:

  1. Restore the original configuration for your identity provider using the previous values:
    • SP Entity ID:   https://id.atlassian.com/login
    • SP Assertion Consumer Service URL:   https://id.atlassian.com/login/saml/acs
  2. If you had SAML single sign-on configured prior to subscribing to Identity Manager, you can go to the SAML single sign-on settings page of your Atlassian Cloud site, and click the Restore my original configuration button (you need to click the 'info' icon to see the button).
  3. Contact Atlassian Support, so we can help figure out what went wrong with your SAML single sign-on configuration, and help fix it.


Remove SAML single sign-on

Before you remove the SAML single sign-on configuration, you should know that your users will need an Atlassian account password to log in.

  • Users who had a password on their Atlassian account before SAML single sign-on was enabled will use that to log in.
  • Users who joined after SAML single sign-on was enabled will need to reset their password for their Atlassian account when they next log in.


To remove SAML single sign-on:

  1. Go to  Application picker Site administration and choose either Organization or  Security, under 'Organizations & Security'.
  2. Choose SAML single sign-on, on the left.
  3. Now scroll down and click Delete configuration. Confirm the deletion.


We recommend that you also go to your identity provider and remove the SAML configuration for Atlassian Cloud there.

Note that removing SAML single sign-on does not unsubscribe you from Identity Manager. If you no longer wish to enforce security policies on your managed accounts, you can contact our support team and we can unsubscribe you from Identity Manager. 


Troubleshoot your SAML configuration

This section describes general troubleshooting for SAML single sign-on with Atlassian accounts. If you've recently updated your SAML single sign-on configuration after Atlassian asked you to, and are now having issues, see the next section.

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

If you're unable to access your Atlassian Cloud products because of the SAML configuration:

  1. Go to your Atlassian account login screen, click Can't log in? and follow the prompts. We'll send you an email with a magic link that lets you log in instantly.
  2. Go to the SAML single sign-on page for your organization to fix or disable SAML sign-on for the rest of your users.
  3. 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 for an Atlassian account password.

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.


Click to see error messages and solutions...

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 identity provider configuration, e.g. a user may not be able to access the Atlassian product 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 for SAML. You had xxx; but we were expecting xxx.

  • "Invalid issuer in the Assertion/Response"

The identity provider 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 identity provider 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 identity provider 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 identity provider's clock is synchronised with NTP.

Frequently Asked Questions

Can I get SAML single sign-on for domains that I cannot verify?

No. To keep products and resources secure, you can only use SAML single sign-on with domains you can verify that you own.  

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

SAML single sign-on isn't available yet for Bitbucket Cloud, Trello, Statuspage, or Jira Service Desk portal-only customer accounts, but we have plans to gradually roll out SAML single sign-on for these products.

How does authentication with REST APIs work?

We recommend that your scripts and services use an API token instead of a password for basic authenticatation with your Atlassian Cloud products. Read more about using API tokens.


Last modified on May 17, 2018

Was this helpful?

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