SAML single sign-on for Atlassian Data Center applications

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 SAML for Atlassian Data Center add-on that allows the following applications to connect to an IdP to provide SSO for your users:

  • JIRA Software Data Center 7.2
  • JIRA Service Desk Data Center 7.2
  • Bitbucket Data Center 4.10
  • Confluence Data Center 6.1

Note that the SAML for Atlassian Data Center add-on 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.

Supported Identity Providers

Once you have installed the SAML for Atlassian Data Center add-on, the solution 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:

Setting up single sign-on

Once you've installed the SAML for Atlassian Data Center add-on, you'll need to configure the add-on and your IdP to provide single sign-on for your users.

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 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 for Atlassian Data Center add-on in your Atlassian application

  1. Navigate to the SAML Authentication screen: 
    • For JIRA applications, select  > System > SAML Authentication
    • For Bitbucket, select  > System > SAML Authentication
  2. Select SAML single sign-on.

    Configure the following settings:

    Setting Notes

    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.

    Login mode

    This defines how your users can use single-sign on. The options are:

    • Use SAML as secondary authentication – the default way to log in will be the standard application login form. You can log in using SAML if you go to your IdP and select your application, or by using the this URL to log in: BASE-URL/plugins/servlet/external-login. We recommended this method so you can test that everything is configured correctly, and that users can log in using SSO.
    • Use SAML as primary authentication – in this mode, all browser-based users will be redirected from the application's login screen to the IdP to log in. It's still possible to authenticate by:
      • Basic Auth
      • Form-based auth via dedicated REST endpoint
      • Existing Remember Me tokens
      • Git HTTP(S) (for Bitbucket Server)
      • Git SSH (for Bitbucket Server)
      You should only enable this mode once you've verified that SAML authentication is working as expected.

    (JIRA Service Desk only)

    When checked, all login requests from your Service Desk customers using the customer portal will be redirected to the configured IdP. If not selected, customers must log in through the customer portal.
  3. The following information is provided on the Authentication screen, and will be required to configure your IdP:

    Setting name Notes
    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.

  4. Click Save configuration.

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

Best practices

  • To ensure security and privacy of your authentication process, you should make sure 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 Atlassian application/s and the IdP are synchronised.
  • If users and groups in your Atlassian 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 restore login form authentication by using issuing a DELETE request (using a username and password for an administrator configured in your user directory):

    curl -u admin_user:admin_password -X DELETE http://base-url/*ContextPathIfAny*/rest/authconfig/1.0/saml
  • 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 the Atlassian support.
  • When using SAML as primary authentication and you have CAPTCHA enabled in the application, users that use HTTP basic authentication (for example in REST resource calls, or when using Git HTTPS in Bitbucket) 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.
Last modified on Mar 20, 2017

Was this helpful?

Yes
No
Provide feedback about this article

Not finding the help you need?

Ask the community

Powered by Confluence and Scroll Viewport.