This page contains information about how to setup Azure AD and User Sync. We currently recommend to setup User Sync on the Azure side with new App registrations interface (preview). Since the new App registrations interface is only a preview, it is possible that Microsoft will change the appearance or wording in the future. When you encounter different wording, please contact us and we will update the documentation.




    Recommended Setup: Via the new App registrations interface (preview)

    Quickstart guide


    Go to portal.azure.com, click "Azure Active Directory" in the left panel and then choose "App registrations (Preview)".


    1. Click on "New registration"
    2. Enter a "Name" for the app.
    3. Set the Redirect URI to "Web" and enter "https://<your-instance>/plugins/servlet/de.resolution.usersync/oauth2/authorize" in the textfield.
    4. Click on "Register".
    5. On this page you can see the "Application ID" and the "Directory (tenant) ID". You will need both to setup the Azure AD connector in User Sync.
    6. Click on "API permissions" in the left panel.
    7. Click on "Add a permission" and choose "Microsoft Graph".
    8. Click on "Delegated permission". Search for the "User" entry and expand it. Tick "User.Read" and "User.ReadBasic.All".
    9. Click on "Add permissions" to finally add the permissions.
    10. Click again on "Add a permission", choose "Microsoft Graph" and click on "Application Permissions".
    11. Search for the "Directory" entry, expand it and tick "Directory.Read.All".
    12. Then, search for "User", expand it and tick "User.Read.All".
    13. Click on "Add permissions" to add the permissions.
    14. Next, click on "Certificate & secrets".
    15. Add a new Client secret by click on "New client secret".
    16. Enter a description, and choose "Never" for "Expires". Click on "Add".
    17. Copy the secret now ("VALUE"). You are not able to see it again after leaving that page.
    18. Setup up the User Sync connector as described above.


    User guide 


    1. Go to http://portal.azure.com and search in the left panel for



    2. In the Azure Active directory, click on "App registrations (Preview)".



    3. Click on "New registration" to create a new App



    4. Enter a name for your application and for the Redirect URI use "https://<your-instance>/plugins/servlet/de.resolution.usersync/oauth2/authorize". Click on register to proceed.



    5. Click on "API permissions" in the left panel and then on "Add a permission".



    6. Select "Microsoft Graph".



    7. Choose "Delegated permissions".



    8. Scroll down to User, make sure that "User.Read" is ticked and tick also "User.ReadBasic.All". Click on "Add permissions" to confirm this.



    9. In the "API permissions" window, click again on "Add a permission".



    10. Now, choose "Application permissions"



    11. Expand "Directory" and tick "Directory.Read.All"



    12. Scroll down to "User" and also tick "User.Read.All"



    13. For the next step, click on "Certificates & secrets" in the left panel, and then click on "New client secret".



    14. Enter a description for the secret and also set an expiry date. Click on "Add" to confirm.



    15. Your Client secret will displayed only once, thus copy the secret. Of course it is possible to create a new secret, if you lost your secret.



    16. In the next steps, you will set up User Sync in your Atlassian application. Click on "Add Connector" and choose "Azure Connector".




    17. Insert the "Application Secret" which were created two steps ago.



    18. For the next step, you need the "Application ID" and the "Directory (tenant ID)". You can find those on the overview page of the Azure AD app. Please insert them into the User Sync configuration in your Atlassian product.



    19. If you provided all information, click on "Authorize":



    20. After a successful authorization, do not forget to save your configuration. Scroll down to the bottom of the page and hit "Save".



    21. You are now ready to toggle a full sync. Simply click the "Sync" button.


    Alternative setups


    While we recommend using the new Application registration user-interface, it is also possible to use the Application Registration Portal and the old App registration.



    Via the Application Registration Portal


    1. Go to https://apps.dev.microsoft.com/#/appList
    2. Click on "Add an app". If you're asked whether you want to use the new Azure Portal experience, choose "Not Now".
    3. Choose any name you like.
    4. Copy the "Application Id" to the field "Client ID" in the UserSync Connector settings.
    5. Generate a new Application Secret, use the Password method. Once it is generated, copy it to the field "Client Secret" in the UserSync Connector settings.
    6. Add a platform, chose "Web" and enter "https://<your-instance>/plugins/servlet/de.resolution.usersync/oauth2/authorize" as the "Redirect URL".
    7. Set Graph Permissions:
      1. Delegated Permissions: User.Read, User.ReadBasic.All
      2. Application Permissions: Directory.Read.All (Admin Only), User.Read.All (Admin Only)
    8. Click on "Save".
    9. Starting with Usersync 1.1.0 / SAML SSO 3.1.0, you also need a Directory (tenant) ID. Follow either https://docs.microsoft.com/en-us/onedrive/find-your-office-365-tenant-id or the steps below:
      1. The easiest way to obtain the tenant ID at this point is to use the new Azure portal experience, which you can access via the banner at the top of the page.
      2. There, you'll immediately see the Directory (tenant) ID. Copy that into the UserSync Connector settings.
    10. Switch to the User Sync settings. Click on "Save", then on "Authorize" and follow the next steps. After you have been redirected to the Connector settings again, you should be able to start the initial sync.

    Via Enterprise applications


    1. Go to "Enterprise Applications" in the Azure Portal.
    2. Click on "New Application" and afterwards on "Application you're developing"
    3. Then, click on "Ok, take me to App Registrations to register my new application." This redirects you to the old "App registrations" interface. Please follow the instructions below.


    Via the old App registrations


    Using the old App registrations interface is also possible. You can access it via the Enterprise applications as described before, or by going to  portal.azure.com and choosing "Azure Active Directory". On the right panel you can now find a link to "App registration".

    1. Click on "New application registrations"
    2. Enter a name, choose "Web app /API" as the Application type. For the sign-on URL use "https://<your-instance>/plugins/servlet/de.resolution.usersync/oauth2/authorize"
    3. Click on "Create" and afterwards on "Settings".
    4. Navigate to "Required Permissions" and click on "Add"
    5. Click on "Select an API" and "Microsoft Graph". Confirm this by clicking on "Select".
    6. On the next window, you have to select the following permissions. Please note, there are "Application Permissions" and "Delegated Permission". Select the following permissions:
      1. Delegated Permissions: "Sign in and read user profile", "Read all users' basic profiles"
      2. Application Permissions: "Read directory data" , "Read all users' full profiles"
    7. Click on "Done" to save the permissions.
    8. Next, click on "Keys" in the left panel.
    9. In "Passwords", enter a "Key description", choose "Never expires" for the duration and press the Save button. 
    10. Now, the password is visible. Copy it, since you can not retrieve it anymore after leaving the page.
    11. Setup up the User Sync connector as described above.