Tutorial: Azure Active Directory integration with Atlassian Cloud

In this tutorial, you learn how to integrate Atlassian Cloud with Azure Active Directory (Azure AD).

Integrating Atlassian Cloud with Azure AD provides you with the following benefits:

  • You can control in Azure AD who has access to Atlassian Cloud.
  • You can enable your users to be signed on automatically (single sign-on) to Atlassian Cloud with their Azure AD accounts.
  • You can manage your accounts in one central location, the Azure portal.

For more information about software as a service (SaaS) app integration with Azure AD, see What is application access and single sign-on with Azure Active Directory?.

Prerequisites

To configure Azure AD integration with Atlassian Cloud, you need the following items:

  • An Azure AD subscription.
  • To enable Security Assertion Markup Language (SAML) single sign-on for Atlassian Cloud products, you need to set up Identity Manager. Learn more about Identity Manager.

Note

When you test the steps in this tutorial, we recommend that you not use a production environment.

To test the steps in this tutorial, follow these recommendations:

  • Do not use your production environment, unless it is necessary.
  • If you don't have an Azure AD trial environment, you can get a one-month trial.

Scenario description

In this tutorial, you test Azure AD single sign-on in a test environment. The scenario outlined in the tutorial consists of two main building blocks:

  • Adding Atlassian Cloud from the gallery
  • Configuring and testing Azure AD single sign-on

To configure the integration of Atlassian Cloud with Azure AD, add Atlassian Cloud from the gallery to your list of managed SaaS apps by doing the following:

  1. In the Azure portal, in the left pane, select the Azure Active Directory button.

    The Azure Active Directory button

  2. Select Enterprise applications > All applications.

    The Enterprise applications pane

  3. To add an application, select New application.

    The "New application" button

  4. In the search box, type Atlassian Cloud, in the results list, select Atlassian Cloud, and then select Add.

    Atlassian Cloud in the results list

Configure and test Azure AD single sign-on

In this section, you configure and test Azure AD single sign-on with Atlassian Cloud, based on a test user named Britta Simon.

For single sign-on to work, Azure AD needs to identify the Atlassian Cloud user and its counterpart in Azure AD. In other words, you must establish a link relationship between an Azure AD user and the related user in Atlassian Cloud.

To establish the link relationship, assign as the Atlassian Cloud Username the same value that's assigned to the Azure AD user name.

To configure and test Azure AD single sign-on with Atlassian Cloud, you need to complete the building blocks in the following sections.

Configure Azure AD single sign-on

In this section, you enable Azure AD single sign-on in the Azure portal and configure single sign-on in your Atlassian Cloud application.

To configure Azure AD single sign-on with Atlassian Cloud, do the following:

  1. In the Azure portal, in the Atlassian Cloud application integration pane, select Single sign-on.

    Configure Single sign-on link

  2. In the Single sign-on window, in the Single Sign-on Mode box, select SAML-based Sign-on.

    Single sign-on window

  3. To configure the application in IDP-initiated mode, under Atlassian Cloud Domain and URLs, do the following:

    Atlassian Cloud domain and URLs single sign-on information

    a. In the Identifier box, type https://auth.atlassian.com/saml/<unique ID>.

    b. In the Reply URL box, type https://auth.atlassian.com/login/callback?connection=saml-<unique ID>.

    c. In the Relay State box, type a URL with the following syntax: https://<instancename>.atlassian.net.

  4. To configure the application in SP-initiated mode, select the Show advanced URL settings and then, in the Sign on URL box, type a URL with the following syntax: https://<instancename>.atlassian.net.

    Atlassian Cloud domain and URLs single sign-on information

    Note

    The preceding values are not real. Update them with the actual identifier, reply URL, and sign-on URL values. You can get the real values from the Atlassian Cloud SAML Configuration screen. We explain the values later in the tutorial.

  5. Under SAML Signing Certificate, select Certificate(Base64), and then save the certificate file on your computer.

    The Certificate download link

  6. Your Atlassian Cloud application expects to find the SAML assertions in a specific format, which requires you to add custom attribute mappings to your SAML Token Attributes configuration.

    By default, the User Identifier value is mapped to user.userprincipalname. Change this value to map to user.mail. You can also choose any other appropriate value according to your organization's setup but, in most of the cases, email should work.

    The Certificate download link

  7. Select Save.

    The Configure single sign-on Save button

  8. To open the Configure sign-on window, in the Atlassian Cloud Configuration section, select Configure Atlassian Cloud.

  9. In the Quick Reference section, copy the SAML Entity ID and SAML Single Sign-On Service URL.

    Atlassian Cloud configuration

  10. To get SSO configured for your application, sign in to the Atlassian portal with administrator credentials.

  11. Go to Atlassian Site Administration > Organizations & Security. If you haven't already done so, create and name your organization and then, in the left pane, select Domains.

    Configure single sign-on

  12. Select the way that you want to verify your domain: DNS or HTTPS.

    Configure single sign-on

  13. For DNS verification, in the Domains window, select the DNS tab, and then do the following:

    Configure single sign-on

    a. To copy the value for your text record (TXT record), select Copy.

    b. To add a record, go to the settings page in your DNS.

    c. Select the option for adding a new record, and then paste the value that you copied in the Domains window to the Value field. Your DNS record might also refer to it as Answer or Description.

    d. Your DNS record may also include the following fields:

    • In the Record type box, enter TXT.
    • In the Name/Host/Alias box, leave the default value (@ or blank).
    • In the Time to live (TTL) box, enter 86400.

    e. Save the record.

  14. Return to the Domains window in organization administration, and then select Verify domain. In the Domain box, type your domain name, and then select Verify domain.

    Configure single sign-on

    Note

    Because it can take up to 72 hours for the TXT record changes to take effect, you won't know right away whether your domain verification was successful. To view your verification status, check the Domains window soon after you've completed this procedure. The updated status will be displayed as Verified, as shown in the following image:

    Configure single sign-on

  15. For HTTPS verification, in the Domains window, select the HTTPS tab, and then do the following:

    Configure single sign-on

    a. To download the HTML file, select Download file.

    b. Upload the HTML file to the root directory of your domain.

  16. Return to the Domains page in organization administration, and select Verify domain. In the Verify domain window, in the Domain box, type your domain name, and then select Verify domain.

    Configure single sign-on

  17. If the verification process can locate the file that you uploaded at the root directory, the status of the domain is updated to Verified, as shown here:

    Configure single sign-on

    Note

    For more information, see Atlassian domain verification.

  18. In the left pane, select SAML single sign-on. If you haven't already done so, subscribe to Atlassian Identity Manager.

    Configure single sign-on

  19. In the Add SAML configuration window, do the following:

    Configure single sign-on

    a. In the Identity provider Entity ID box, paste the SAML entity ID that you copied from the Azure portal.

    b. In the Identity provider SSO URL box, paste the SAML single sign-on service URL that you copied from the Azure portal.

    c. Open the downloaded certificate from the Azure portal in a .txt file, copy the value (without the Begin Certificate and End Certificate lines), and then paste it in the Public X509 certificate box.

    d. Select Save Configuration.

  20. To ensure that you have set up the correct URLs, update the Azure AD settings by doing the following:

    Configure single sign-on

    a. In the SAML window, copy the SP Identity ID and then, in the Azure portal, under Atlassian Cloud Domain and URLs, paste it in the Identifier box.

    b. In the SAML window, copy the SP Assertion Consumer Service URL and then, in the Azure portal, under Atlassian Cloud Domain and URLs, paste it in the Reply URL box.
    The sign-on URL is the tenant URL of your Atlassian Cloud.

    Note

    If you're an existing customer, after you update the SP Identity ID and SP Assertion Consumer Service URL values in the Azure portal, select Yes, update configuration. If you're a new customer, you can skip this step.

  21. In the Azure portal, select Save.

    Configure single sign-on

Tip

As you're setting up the app, you can read a concise version of the preceding instructions in the Azure portal. After you add this app from the Active Directory > Enterprise Applications section, select the Single Sign-On tab, and then access the embedded documentation in the Configuration section at the bottom of the window. For more information, see Azure AD embedded documentation.

Create an Azure AD test user

In this section, you create test user Britta Simon in the Azure portal by doing the following:

Create an Azure AD test user

  1. In the Azure portal, in the left pane, select the Azure Active Directory button.

    The Azure Active Directory button

  2. To display the list of users, select Users and groups > All users.

    The "Users and groups" and "All users" links

  3. In the All Users window, select Add.

    The Add button

  4. In the User window, do the following:

    The User window

    a. In the Name box, type BrittaSimon.

    b. In the User name box, type the email address of user Britta Simon.

    c. Select the Show Password check box, and then write down the value that's displayed in the Password box.

    d. Select Create.

Create an Atlassian Cloud test user

To enable Azure AD users to sign in to Atlassian Cloud, provision the user accounts manually in Atlassian Cloud by doing the following:

  1. In the Administration pane, select Users.

    The Atlassian Cloud Users link

  2. To create a user in Atlassian Cloud, select Invite user.

    Create an Atlassian Cloud user

  3. In the Email address box, enter the user's email address, and then assign the application access.

    Create an Atlassian Cloud user

  4. To send an email invitation to the user, select Invite users.
    An email invitation is sent to the user and, after accepting the invitation, the user is active in the system.

Note

You can also bulk-create users by selecting the Bulk Create button in the Users section.

Assign the Azure AD test user

In this section, you enable user Britta Simon to use Azure single sign-on by granting access to Atlassian Cloud. To do so, do the following:

Assign the user role

  1. In the Azure portal, open the Applications view, go to the directory view, and then select Enterprise applications > All applications.

    Assign User

  2. In the Applications list, select Atlassian Cloud.

    The Atlassian Cloud link in the Applications list

  3. In the left pane, select Users and groups.

    The "Users and groups" link

  4. Select Add and then, in the Add Assignment pane, select Users and groups.

    The Add Assignment pane

  5. In the Users and groups window, in the Users list, select Britta Simon.

  6. In the Users and groups window, select Select.

  7. In the Add Assignment window, select Assign.

Test single sign-on

In this section, you test your Azure AD single sign-on configuration by using the Access Panel.

When you select the Atlassian Cloud tile in the Access Panel, you should be signed on automatically to your Atlassian Cloud application. For more information about the Access Panel, see Introduction to the Access Panel.

Additional resources