Learn about security solutions and standards
Care about security? We do too. Learn what Atlassian does and what you can do too.
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? |
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 Guard Standard from your organization. Understand Atlassian Guard
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.
Identity provider | Setup instructions |
|---|---|
Active Directory Federation Services (AD FS) | |
Auth0 | |
CyberArk (Idaptive) | |
Google Cloud | SAML single sign-on with Google Cloud for Atlassian (different to Google Workspace setup) |
JumpCloud | |
Microsoft Azure AD | |
miniOrange | |
Okta | |
OneLogin | Log in to OneLogin to see these pages. |
PingFederate |
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
Go to admin.atlassian.com. Select your organization if you have more than one.
Select Security > Identity providers.
Select your identity provider Directory.
Select Set up SAML single sign-on.
Add SAML details.
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:
Open a new incognito window in your browser.
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:
Go to admin.atlassian.com. Select your organization if you have more than one.
Select Security > Authentication policies.
Select Edit for the policy you want to configure.
When you select Use SAML single sign-on, we redirect you from the authentication policy to the SAML SSO configuration page.
Once you're done configuring SAML SSO, you need to enforce SSO in the policy.
To enforce single sign-on:
Go to admin.atlassian.com. Select your organization if you have more than one.
Select Security > Authentication policies.
Select Edit for the policy you want to enforce.
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:
Link domains to your identity provider directory
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
Link domains for Just-in-time provisioned users with SAML
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:
Go to admin.atlassian.com. Select your organization if you have more than one.
Select Security > Identity providers.
Select the Directory you'd like to view.
Select View domains to link the domain to the directory.
Select Link domain.
Select one or many domains to link to the directory.
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
If you change an email in your identity provider, you must manually update the email in Atlassian.
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 Guard Standard, 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:
Go to admin.atlassian.com. Select your organization if you have more than one.
Select Security > Identity providers.
Select the Directory you'd like to view.
Select View SAML configuration.
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 Guard Standard. If you no longer need Atlassian Guard Standard 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
Before you configure SAML, create an Atlassian user account with an email from an unverified domain.
Make the user an organization admin.
Log in with the account to troubleshoot since you won't have to authenticate with SAML.
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
Before you configure SAML, create an Atlassian user account with an email from an unverified domain.
Make the user an organization admin.
Add the user to an authentication policy without SAML single sign-on enforced.
Log in with the account to troubleshoot since you won't have to authenticate with SAML.
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:
Copy and paste the certificate again. Make sure to copy and paste:
All the lines in the certificate.
Start from “-----BEGIN CERTIFICATE-----” and end with “-----END CERTIFICATE-----'.
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. |
| You're most likely using an unsupported IdP. Verify your IdP configuration by making sure you've done the following:
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. |
| 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
Was this helpful?
Still need help?
The Atlassian Community is here for you.