Security Assertion Markup Language (SAML) is an XML-based data format that allows a service to exchange authorization data with an identity provider (IdP). The most common use case is allowing a user to sign in to multiple software applications using the same authentication details, usually a username and password. This is referred to as single sign-on (SSO).

Atlassian provides the SSO for Atlassian Server and Data Center app that allows Jira Server and Data Center applications to connect to your IdP so that you can provide your users with an SSO experience.

SSO for Atlassian Server and Data Center only handles authentication. Application access and any required authorizations, such as ensuring that users belong to the appropriate groups/roles and have the necessary permissions, should be configured in the user directory and/or the application itself.

Setting up single sign-on

You'll need to configure your application and your IdP to provide single sign-on for your users.

Supported identity providers

SAML single sign-on should work with any identity provider implementing the SAML 2.0 Web Browser SSO Profile, using the HTTP POST binding.

We currently perform tests with the following identity providers:

• Microsoft Active Directory (using ADFS 3.0)
• Microsoft Azure Active Directory
• OneLogin
• Okta
• PingIdentity

Setting up SSL/TLS

Setting up your identity provider

If you want your application to provide SSO, you'll need to add it to your IdP. The exact process varies depending on the IdP, but you'll usually need to:

• Define an "application" in your IdP.
• Provide some data about the application, including data you can access on your application's Authentication methods screen.
• Make sure the NameID attribute of the users in your IdP is set to the username in your Atlassian application.
• Give the appropriate users permission to use the application.

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.

Configuring SAML SSO authentication in your Atlassian application

1. Open the Authentication methods screen by selecting Administration () > System > Authentication methods.
2. Select Add configuration.
3. In the Authentication method menu, select SAML single sign-on.
4. Create a unique name for your configuration.

5. Configure the following SAML SSO settings:

   Setting	Details
   Single sign-on issuer	This value is provided by your IdP, as part of setting up SAML. It's sometimes also called "Entity ID". The issuer is the IdP your application will be accepting authentication requests from.
   Identity provider single sign-on URL	This value is provided by your IdP, as part of setting up SAML. It defines the URL your users will be redirected when logging in.
   X.509 Certificate	This value is provided by your IdP, as part of setting up SAML. This is sometimes referred to as a "Signing certificate". The key usually starts with "-----BEGIN CERTIFICATE-----". This contains the public key we'll use to verify that all received SAML authentication requests have been issued by your IdP.
   Remember user logins	If selected, successful user logins will be remembered in the user's browser. When browsing their application, users will be logged in automatically without having to authenticate again using SAML.
   Username mapping	An attribute from your IdP that uniquely identifies a user and can be mapped to the username in Jira. For example, if you entered ${NameID}, we would use the values of this attribute from your IdP as usernames. Check your IdP docs for the list of attributes.

6. The following information is provided on the Authentication methods screen and will be required to configure your IdP. Copy and paste these links to your identity provider:

   Setting	Details
   Assertion Consumer Service URL	This is the URL the IdP will return SAML authentication requests to.
   Audience URL (Entity ID)	This is the URL the IdP will prepare SAML authentication requests for.

7. The following settings are optional and can be configured as you see fit:
   

   Setting	Details
   JIT provisioning	If Create users on login to the application is selected, users will be created and updated automatically when they log in through SSO to Atlassian Data Center applications. See JIT user provisioning for details.
   SAML SSO behaviour	If Remember user logins is selected, users will be logged in automatically as their login information will be remembered.
   Include customer logins (Jira Service Management only)	If selected, all login requests from your Jira Service Management customers using the customer portal will be redirected to the configured IdP. If not selected, customers will have to log in through the customer portal.
   Login page settings	If Show IdP on the login page is selected, users will see identity provider on login page.

8. Select Save configuration.

Once you've configured both your application and your IdP, you're ready to start using SSO.

Best practices

• To ensure the security and privacy of your authentication process, make sure that 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.
• SAML authentication requests are only valid for a limited time. You should make sure the clocks on the server running your application/s and the IdP are synchronized.
• If users and groups in your application are configured using User Directories, you'll usually want to use the same LDAP directory to be the source of users for both your IdP and Atlassian application. Users need to exist in the user directory before they can log in using SSO.

Troubleshooting

• If you make a mistake configuring the SAML authentication, or are unable to log in using your IdP,  you can bypass SAML authentication by using the auth_fallback functionality. See Bypass SAML authentication for Jira Data Center for details. 

• If an authentication error occurs, the user will only see basic details about what went wrong. For security reasons, the details about the underlying problem are not shown. You'll need to check the application logs to see the cause of the problem. 
• In some cases, you might also experience errors shown by your IdP. For those, you will need to use the support and tools provided by your IdP, rather than Atlassian support.
• If you use SAML as primary authentication and have CAPTCHA enabled in the application, users that use HTTP basic authentication (for example in REST resource calls) may get locked out if they enter an incorrect password too many times. In these cases, an administrator will need to reset the user's CAPTCHA in the user list screen.