robotsnoindex


If you recently noticed a change in your authentication settings
Beginning the week of March 15th, we started migrating SAML single sign-on and other settings to your new authentication policies. Learn about what's changed



SAML single sign-on is available when you subscribe to Atlassian Access. Read about how to start with Atlassian Access.

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

SAML for single sign-on (SSO) makes it possible for 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. Note that SSO will only apply to user accounts 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 Update product access settings for how to do that.

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

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 giving you the ability to test different single sign-on configurations on limited subsets of users before rolling them out to your whole company.

When you configure your security settings with authentication policies, you’ll need to enforce SAML or G Suite SSO within the authentication policy. Visit edit authentication settings and members for how to do it.

Before you begin

There are a couple of things you need to do before you can apply SAML single sign-on to your user's Atlassian accounts:

  1. Verify one or more domains – Learn about verify a domain for your organization.

  2. Subscribe to Atlassian Access.

Furthermore, we recommend that you check the following: 

  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 misconfigured. 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 Atlassian Access before you can set up SAML single sign-on for your managed users. See Atlassian Access security policies and features 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.

If your identity provider is listed here, then use the identity provider instructions to set up SAML single sign-on.


Set up SAML single sign-on for other identity providers

If your identity provider isn't listed , you can still set up SAML single sign-on with the following steps.

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 pass an email address value using the NameId attribute. When you add the Atlassian product, add the following SAML attribute mappings to your identity provider:

SAML attribute nameWhat 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 the user that will not change.

Note that this Id should NOT be the user's email address.

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

    From your organization at admin.atlassian.com,

     select Security and then SAML single sign-on.

  2. Click Add SAML configuration.

  3. Copy your identity provider details to these fields:

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

Confirm you are signed in 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.

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.


Test SAML single sign-on with Authentication policies

Starting mid-March to the end of April 2021, we’ll roll out authentication policies. The way you test SAML single sign-on will change. When you have authentication policies, you’ll use them to test SAML single sign-on. Read this section for how to do it.

Authentication policies give you the flexibility to configure multiple security levels for different user sets within your organization. Authentication policies also reduce risk by giving you the ability 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 set up 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 next section provides instructions for how to do it.

Configure and enforce SAML single sign-on with authentication policies

You’ll need to configure and save SAML and then enforce SAML single sign-on in an authentication policy.

To configure SAML single sign-on from Authentication policies:

  1. Navigate to Authentication policies at admin.atlassian.com.

  2. Select Edit for the policy you want to configure.

  3. When you select Use SAML single sign-on, you’re redirected from the authentication policy to the SAML SSO configuration page.

  4. Once you’re done configuring SAML SSO, you need to enforce SSO in the policy.

To enforce single sign-on:

  1. Navigate to Authentication Policies at admin.atlassian.com.

  2. Select Edit for the policy you want to enforce.

  3. Select Enforce single sign-on.

Just-in-time provisioning with SAML

If self signup is enabled, you don't have to manually create an Atlassian account for the new user. When that user logs in for the first time with SAML, we automatically create an Atlassian account for them.

When new users visit Jira, Confluence, or Bitbucket for the first time:

  1. They'll enter their email address.
  2. The login screen for your identity provider appears and they'll enter credentials to authenticate.
  3. We'll ask them to verify their Atlassian account email address by checking their email.
  4. They'll click the verification link from their email to log in, which will open the original site (Jira, Confluence, or Bitbucket) they visited.

You can see the multiple cloud sites you have access to, in one place at start.atlassian.com.

Just-in-time provisioning with authentication policies

Every organization has a default authentication policy with login settings for its users. When you provision new accounts, we add new users to your default policy.

  • For just-in-time provisioning to work with authentication policies, you must enforce SAML single sign-on for a default policy.

  • If you don’t want to enforce SAML single sign-on for your default policy, you can provision users with SCIM. If you make changes to an email account in your identity provider, we automatically make the changes to the Atlassian account.

Learn more about authentication policies.

Troubleshoot email updates without just-in-time provisioning

  1. If you make changes to an email in your identity provider, you have to manually update the email in Atlassian.

  2. If you don’t update the first Atlassian email, we create a second email account when the user logs in. This account won’t have access to any sites or products. To correct this, you can update the first email account or delete it. Update the email of the account.

Deactivate users with SAML

To prevent a user from retrieving your organization's data via the REST API, deactivate the user in both places – from your organization and from your identity provider.

If you also set up user provisioning for your organization, you only need to deactivate the user from your identity provider.


Reuse email addresses for different users

If a user is no longer using an email address (e.g. they left the company), you can assign that email address to another user. But first, you need to make the email address available for the new account to prevent the new user from getting content for the old account.

To make the email address available:

  1. From the Managed accounts page, open the account details of the user who no longer needs the email address. If you deleted the account from your identity provider, the account will be deactivated.
  2. Select Delete account. See Delete a managed account for more details and what happens when you delete an account.

The email address is no longer linked to the deleted user's account and you can assign it to another user.


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.


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

    From your organization at admin.atlassian.com,

     select Security and then SAML single sign-on.

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

Note that removing SAML single sign-on does not unsubscribe you from Atlassian Access. If you no longer wish to enforce security policies on your managed accounts, you can unsubscribe from Atlassian Access.


Troubleshoot your SAML configuration

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

If users cannot access your Atlassian cloud products because of the SAML configuration, go to your Atlassian account login screen, click Can't log in? and follow the prompts.

If resetting the password doesn't help, you can troubleshoot from admin.atlassian.com with an account you set up to help with troubleshooting.

Troubleshooting your SAML configuration

  1. Before you configure SAML, create an Atlassian user account with an email from an unverified domain.

  2. Make the user an organization admin.

  3. Log in with the account to troubleshoot since you won't have to authenticate with SAML.

  4. Go to the SAML single sign-on page for your organization to fix or disable it for all your users.

If you're still having trouble, delete the SAML configuration to go back to password authentication with an 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.

Troubleshooting your SAML configuration with Authentication policies

  1. Before you configure SAML, create an Atlassian user account with an email from an unverified domain.

  2. Make the user an organization admin.

  3. Add the user to an authentication policy without SAML single sign-on enforced.

  4. Log in with the account to troubleshoot since you won't have to authenticate with SAML.

  5. Go to the SAML single sign-on page for your organization to fix or disable it for all your users.

If you want to delete a SAML configuration, make sure that none of your authentication policies use SAML single sign-on.

If you want to prevent lockout for a user, you need to move the user to a policy that does not enforce SAML single sign-on.

Troubleshooting specific errors and possible issues

Include the SAMLRequest and SAMLResponse payloads you can find from the SAML Tracer Firefox add-on when you submit a support ticket. We can 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 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 that is unique and unchanging is mapped to the upn or name SAML attribute.

  3. The SAML responses are signed and not encrypted.

  4. The identity provider's clock is synchronised with NTP.


Note that the internal user Id should be a value that will not change. This Id should NOT be the user's email address.

If necessary, you can change the upn or name attribute to a value that is unique and unchanging. The SAML identity for that Atlassian account will get updated with the new value when the user next logs in.




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.

How do I change the user's full name?

You can update the user's Full name by updating First name and Last name in your identity provider's system. The updated name will be synced to your organization when the user next logs in.

How does authentication with REST APIs work?

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