• Products
  • Documentation
  • Resources

Configure SAML single sign-on with an identity provider

You can now find SAML single sign-on in the same place you manage your identity provider. Select Security > Identity providers. About identity providers

Who can do this?
Role: Organization admin
Plan: Atlassian Access

About SAML single sign-on

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) allows 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. SSO only applies to user accounts from your verified domains. How to verify a domain

Once your users can log in using SAML single sign-on, you need to give access to your Atlassian products and sites. How to update product access settings and How users get site access

If you manage users for a site with Google Workspace, you'll need to use the SSO feature provided by Google Workspace. How to connect to Google Workspace

SAML single sign-on with authentication policies

When you configure SSO with SAML or Google Workspace, you'll need to enforce SSO on subsets of users through your authentication policies. How to edit authentication settings and members

Before you begin

Here's what you must do before you set up SAML single sign-on:

Subscribe to Atlassian Accessfrom your organization. Understand Atlassian Access

Make sure you're an admin for an Atlassian organization.

Verify one or more of your domains in your organization. How to verify a domain  

Add an identity provider directory to your organization. How to add an identity provider

Link verified domains to your identity provider directory. How to link domains

Check that your Atlassian product and your identity provider use the HTTPS protocol to communicate and that the configured product base URL is the HTTPS one.

Here’s what we recommend you do before you set up SAML single sign-on:

Make sure the clock on your identity provider server is synchronized with NTP. SAML authentication requests are only valid for a limited time.

Plan for downtime to set up and test your SAML configuration

Create an authentication policy to test your SAML configuration
. Add a user to the test policy. After you set up SAML, you can enable single sign-on for the test policy.

Supported identity providers

You can use the identity provider of your choice, but some capabilities are only available with selected identity providers. Supported identity providers

The steps involved to set up single sign-on will differ depending on the identity provider you use. Refer to the setup instructions for your identity provider.

Available SAML attributes

When you set up your identity provider, these are the SAML attributes you use:

Instructions

SAML Attribute

Map to your identity provider

Optional

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,  ORhttp://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.

Required

NameID

User’s email

Copy details from your identity provider to your Atlassian organization

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

  2. Select Security > Identity providers.

  3. Select your identity provider Directory.

  4. Select Set up SAML single sign-on.

  5. Add SAML details.

  6. Save SAML configuration.

SAML details

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.

Copy these URLs from your Atlassian organization to your identity provider

  • Service provider entity URL

  • Service provider assertion consumer service URL

Select Save in your identity provider when you copy the URLs.

Set up SAML single sign-on for other identity providers

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

Test SAML single sign-on configuration without authentication policies

If you’re unable to see authentication policies, create a temporary Atlassian test account you can use to access your organization. Use an email address for the temporary account from a domain you have not verified for this organization. This ensures that the account won't redirect to SAML single sign-on when you log in.

When you select Save configuration, we apply SAML to your Atlassian organization. Because we don't log out your users, use these steps to test SAML configuration:

  1. Open a new incognito window in your browser.

  2. Log in with an email address from one of your verified domains.

Confirm you're signed in. If you experience a login error, go to the Troubleshooting SAML single sign-on to adjust your configuration and test again in your incognito window.

If you can't log in successfully, delete the configuration so users can access Atlassian products.

Test 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 allowing you 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 setup 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 following section provides instructions on 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. Go to admin.atlassian.com. Select your organization if you have more than one.

  2. Select Security > Authentication policies.

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

  4. When you select Use SAML single sign-on, we redirect you from the authentication policy to the SAML SSO configuration page.

  5. Once you're done configuring SAML SSO, you need to enforce SSO in the policy.

To enforce single sign-on:

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

  2. Select Security > Authentication policies.

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

  4. Select Enforce single sign-on.

Just-in-time provisioning with SAML

If you’d like to provision users with SAML Just-In-Time, you must complete these two steps:

  1. Link domains to your identity provider directory

  2. Enforce SAML single sign-on on a default authentication policy

After you complete the steps, when a user logs in for the first time with SAML, we automatically create an Atlassian account for them and they are provisioned through SAML to your identity provider directory. Learn more about identity provider directories

If you'd like to provision users with SAML Just-In-Time, you must link one or more domains to your identity provider directory. After you link a domain, we'll automatically associate the domain's user accounts to the directory.

To link domains to a directory:

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

  2. Select Security > Identity providers.

  3. Select the Directory you'd like to view.

  4. Select View domains to link the domain to the directory.

  5. Select Link domain.

  6. Select one or many domains to link to the directory.

Learn about linked domains

Just-in-time provisioning with Authentication policies

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

  • 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 change your identity provider's email, we automatically update the Atlassian account.

Learn more about authentication policies

Troubleshoot email updates without just-in-time provisioning

  1. If you change an email in your identity provider, you must 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. You can update the first email account or delete it to correct this. Update the email of the account

Set up automated user provisioning and de-provisioning

Automated user provisioning allows for a direct sync between your identity provider and your Atlassian Cloud products. You no longer need to manually create user accounts when someone joins the company or moves to a new team.

Automated de-provisioning reduces the risk of information breaches by removing access for those that leave your company. We automatically remove people when they leave the company or a group. This gives you control over your bill. Here are your options for user provisioning:

  • Provisioning with SCIM - With a subscription to Atlassian Access, you can sync Atlassian cloud tools directly with your identity provider to enable automated provisioning and de-provisioning of your users and groups. Understand user provisioning

  • Provisioning with Google Workspace - You can sync Atlassian cloud tools with Google Workspace for provisioning. However, any group categorization will not be reflected on your site. Connect to Google Workspace

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 your identity provider.

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


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 requirements and two-step verification are essentially "skipped" during the login process. 

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

Delete SAML single sign-on

Before you delete the SAML single sign-on configuration, make sure your users have a password to log in.

  • Users can use the password they had for their Atlassian account before you enabled SAML single sign-on

  • Users who joined after SAML single sign-on after you enabled need to reset their password for their Atlassian account next time they log in.

To delete SAML single sign-on:

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

  2. Select Security > Identity providers.

  3. Select the Directory you'd like to view.

  4. Select View SAML configuration.

  5. Select Delete configuration.

We recommend you also delete the SAML configuration from your identity provider.

When you delete SAML single sign-on, you still have a subscription toAtlassian Access. If you no longer need Atlassian Access you’ll need to cancel your subscription. How to unsubscribe


Troubleshoot your SAML configuration

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

Troubleshoot SAML single sign-on without 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. 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.

Troubleshoot SAML single sign-on 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 SAML single sign-on for your identity provider directory to 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.

Troubleshoot your Public x509 Certificate errors

If you experience certificate errors, try one of these steps to resolve your error:

  1. Copy and paste the certificate again. Make sure to copy and paste:

    1. All the lines in the certificate.

    2. Start from “-----BEGIN CERTIFICATE-----” and end with “-----END CERTIFICATE-----'.

  2. The certificate your identity provider gave you may be incomplete. Download and copy and paste the certificate into the Public x509 Certificate field.

Troubleshoot other errors

Include the SAMLRequest and SAMLResponse payloads you can find from the SAML Tracer Firefox app when you submit a support ticket. We can more quickly identify potential causes of issues.

Errors

Possible Issues

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

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

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

  • "We were expecting an email address as the Name Id, but we got xxx. Please ask your admin 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 admin to check that Name Id is mapped to email address."

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

  • "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 does 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 the 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 synchronized 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 unique and unchanging value. The SAML identity for that Atlassian account will update the new value when the user next logs in.










"We couldn't log you in, but trying again will probably work."

SAML configuration was disabled for the people during the login process. Verify the SAML configuration 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.

"Your email address has changed at your Identity Provider. Ask your admin 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.

A plain error screen with no Atlassian branding.

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

An error screen for your IdP.

You might have an issue with your identity provider configuration; for example, a user may not access the Atlassian product from the IdP. Raise a ticket with your IdP to fix the issue.

  • We were expecting you to arrive with a different Identity Provider Entity Id. Ask your admin 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.

Frequently Asked Questions

Can I get SAML single sign-on for domains that I can't 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 the first and last names 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. When you enforce SAML, your API tokens and your scripts will continue to work. About API tokens

Additional Help