How to Configure OAuth 2.0 for Azure DevOps

The guide is specifically designed for organizations that manage their identities and access through Microsoft Entra ID (formerly Azure Active Directory). This article will walk you through the essential steps for configuring your Exalate node with OAuth 2.0.

Understanding OAuth 2.0 Permissions

When you configure OAuth 2.0 authentication for Azure DevOps, Exalate will request specific permissions necessary for synchronization. These permissions follow the principle of least privilege, requesting only what's needed for Exalate to function properly.

Permissions Requested

During the OAuth consent process, you will be asked to grant the following permissions:

Azure DevOps Permissions:

• Work items (read and write) - Required to read and update work items during synchronization
• Identity (read) - Required to access user identity information
• Project and team (read) - Required to access project and team information
• MemberEntitlement Management (read) - Required to access organization membership information
• User profile(read) - Required to access basic user profile information

Microsoft Graph Permissions:

• View users' basic profile - Required to view user information

Important Notes

• These permissions align with what you would configure in a custom-defined Personal Access Token (PAT).
• Admin consent is required to grant these permissions for the entire organization. Every user of the organization will have all these permissions.  They will not get a consent pop-up.
• Provided consent on behalf of the organization allows the admin to grant consent for all users in the organization.

Register a New App

1. Navigate to Azure Portal
2. Sign in using an organizational account that has sufficient permissions to register applications within your Microsoft Entra ID tenant
3. Once signed in, in the Azure portal search bar, type App registrations and select the App registrations service.
4. Click on the Button New Registration
5. Fields to fill:
   • Name
   • Who can use this application or access this API?
   • Accounts in this organizational directory only (Default Directory only - Single tenant)
   • Redirect URI
     • select Web
     • append /azure/callback to your Exalate URL (you can find the Exalate URL on the Registration page)
     • Example: Product HTML page - Exalate
       
6. After filling in all the required fields, click the Register button at the bottom of the page to create your application registration.

Note: Client ID and Tenant ID values will be required when you proceed with registering your Exalate node.

Generate Client Secret

Note: Check the How to Generate Client Secret for more details.

Note: Make sure your organization is connected to the default directory.

Configure OAuth 2.0 in Exalate

After creating your app registration and generating the client secret, follow these steps to configure OAuth 2.0 in Exalate:

1. Navigate to your Exalate node's General Settings
2. Select OAuth 2.0 as the authentication method
3. Enter the following credentials:
   • Client ID (from your app registration)
   • Tenant ID (from your app registration)
   • Client Secret (generated in the previous step)
4. Click the Save button 

Permissions Consent

When you click Accept, a Microsoft permissions consent window will appear showing all the permissions that Exalate requires (as listed in the "Understanding OAuth 2.0 Permissions" section above).

At this point, you have two options:

Option 1: Grant consent for yourself only

• Simply review the permissions and click Accept
• You will be able to use Exalate with OAuth 2.0 authentication
• Other users will need to accept their own consent if they want to change the general settings

Option 2: Grant consent on behalf of the organization 

• Check the box "Provide consent on behalf of the organization"
• Click Accept
• This grants permissions for all users in your organization
• Other users will not see the consent window when they change the general settings

Important Note:

If an admin has already granted consent on behalf of the organization, whoever has access to the admin console will not see the permissions consent window when they change General Settings.

The permissions are automatically configured through the OAuth flow, no manual setup in the Azure Portal is required.

Alternative: Manually Add API Permissions in Azure Portal

If you prefer to manually configure API permissions in Azure Portal before setting up OAuth 2.0 in Exalate, you can follow these steps. Note that the available options depend on your role in the directory.

Prerequisites: Understanding User Roles

Your ability to grant permissions depends on your role in Microsoft Entra ID (Azure AD):

• Directory Admin Role: Can grant admin consent for the entire organization (all users)
• Member Role: Can create app registrations and add API permissions for themselves
• Guest Role: Cannot create app registrations in the directory

Steps to Add API Permissions

In Azure Portal, navigate to your app registration

1. Click on API permissions in the left menu
   
2. Click Add a permission
3. Select Azure DevOps and add the following permissions:

• Work items (read and write)
• Identity (read)
• Project and team (read)
• MemberEntitlement Management (read)
• User.Read (User profile - read)
  
  

Granting Consent

After adding the API permissions, the consent process differs based on your role:

If you have Admin Role in the Directory the "Grant admin consent for [your directory]" button will be active

• Click this button to grant consent for all users in your organization
• All users will be able to use OAuth 2.0 authentication without needing to provide their own consent
• This is the equivalent of checking "Provide consent on behalf of the organization" in the automatic flow

If you have Member Role in the Directory the "Grant admin consent for [your directory]" button will be disabled/grayed out

• You can only add API permissions for your own user account
• Other users in your organization will need to accept their own consent if they want to change the general settings
• Each user will see the permissions consent window when they first configure OAuth 2.0 in General Settings

Important Notes:

The manual approach achieves the same result as the recommended automatic consent flow, but requires additional configuration steps in Azure Portal

Switching from PAT to OAuth 2.0

If you have an existing Exalate node configured with Personal Access Token (PAT) authentication and want to switch to OAuth 2.0:

1. Register your app in Azure Portal following the steps in "Register a New App"
2. Generate a Client Secret
3. In your Exalate node's General Settings, change the authentication method to OAuth 2.0
4. Enter your Client ID, Tenant ID, and Client Secret
5. Click Save
6. Review the permissions in the consent window
7. Check the box "Provide consent on behalf of the organization" to grant access for all users
8. Click Accept to complete the setup

The OAuth token will have the same functional permissions as your PAT, but with better security and granular control.