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.
When you encounter different wording, please contact us and we will update the documentation.



Recommended Setup: Via the new App registrations interface

Quickstart guide

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

  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. Please paste it to a text editor for the tutorial.


Now it is time to configure UserSync in your Atlassian product. Please keep the Azure website open, because we will need it later on.

  1. Now, go back to your Atlassian product, and go to the UserSync Configuration.
  2. Click Add Connector and choose Azure Connector.
  3. First, paste the client secret (which you copied before) into the Application Secret.
  4. Next, go back to the Azure website and click Properties in the app you have created for UserSync. Copy the Application ID and Directory (Tenant) ID and paste them into the UserSync configuration in your Atlassian product.
  5. In the UserSync configuration, activate Enable Scheduled Synchronization. You can provide a Cron expression to set a synchronisation interval.


User guide 

Configure Azure AD for UserSync

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



In the Azure Active directory, click on "App registrations".



Click on "New registration" to create a new App



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.



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



Select "Microsoft Graph".



Choose "Delegated permissions".



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



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



Now, choose "Application permissions"



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



Scroll down to "User" and also tick "User.Read.All". Afterwards click "Add permissions" to continue.



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



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



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.


Setting up UserSync in your Atlassian product

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




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



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.



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


To take the full advantages of User Sync, scroll down and tick "Enable Scheduled Synchronization". You can control the sync interval via a Cron Expression.

Do not forget to save your configuration. Scroll down to the bottom of the page and hit "Save".



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 App registration (Legacy).



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 the App Registrations (Legacy)


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 (Legacy)".

  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.