OneConnect supports multiple authentication options to connect to Azure DevOps. 

Please review the options available and choose the best option for your company, before beginning the integration setup. 

Please ensure the person enabling the integration permissions has the necessary administrative rights to do so. 

URL + Personal Access Token

To authenticate to Azure DevOps, provide the Azure DevOps organization URL along with a Personal Access Token (PAT) from an account that has access to site. 

It is recommended to use a dedicated user account for this connection. Best practice dictates one user account per integration to avoid data throttling and potential strategy failures by Microsoft. 

Pros of using PAT:

• Quick to set up.

Cons of using PAT:

• Accounts used with PAT must have read/write/manage access to all connected items being used in the integration. 
• Personal Access Token has an expiration date. PAT must be manually extended or regenerated and re-entered into the integration.
• Single point of failure – If user leaves company, the integration will fail, until another user generates a PAT.

Generate A Personal Access Token

To generate a Personal Access Token, the person needs to be a Project Collection Administrator in Azure DevOps:

1. Log into Azure DevOps.
2. Navigate to User Settings > Personal Access Tokens.
3. Click on the + New Token button.
4. Give the token a Title (e.g., OneConnect Integration).
5. Select the Organization that will be accessed by this token.
6. Select an expiration date for the Token (tokens can be valid for up to 1 year, please keep this in mind for renewing your Azure DevOps token in the future).
7. In Scopes, select:
   • Identity – Read & Manage
   • Work Item – Read, Write, & Manage
8. Click Create.

URL + Service Principal (New)

Connecting to Azure DevOps using a Service Principal is an alternative to using Personal Access Tokens. Service Principals are available to Microsoft Entra ID (formerly Azure AD) backed organizations only.

To authenticate to Azure DevOps, provide the URL of the Azure DevOps Organization, check the Use a Service Principal to connect to Azure DevOps checkbox, along with the Service Principal credentials within the Client Id and Client Secret fields. 

Pros of Service Principal:

• More secure than personal access tokens (which are bearer tokens)

Cons of Service Principal:

• More involved process to set up (requires a Microsoft tenant administrator to approve permissions).
• Customer responsible for maintaining the client secret for the Entra Application. (update it when expires)

Creating a Service Principal

There are currently two ways to set up a service principal to connect to Azure DevOps: Using a Default OnePlan Application, or using a custom Entra Application.

Authorize Button (Default OnePlan Application)

If you want to use the default OnePlan application, please follow the steps below.

Within the Azure DevOps connector, expand the Advanced Options section a Microsoft tenant administrator must click the Authorize button within the connector. This will prompt a login screen where the tenant administrator will need to enter their credentials.

That will add an Entra Application named OneConnect Azure DevOps Authentication to your tenant. The OneConnect Azure DevOps Authentication application will have the following delegated permissions:

• Microsoft Graph: User.Read

If using the Default OnePlan Application, skip to Setting up your Service Principal in Azure DevOps.

Custom Entra Application

The Service Principal is an  registered application within your Azure Active Directory (AAD) that acts as a trusted identity for your integrations. This method requires:

• Application (Client) ID: A unique identifier for the registered application.
• Client Secret: A securely generated password used to authenticate the application.

If you want to use this method, please follow the steps below using your tenant administrators credentials.

Register the Application

1. While logged in as a tenant or application administrator for your tenant, log in to portal.azure.com.
2. Navigate to Microsoft Entra Admin Center.
3. Within the left navigation bar, click on App registrations.
4. On the top left of the page, create a New registration.
   • Name: Give the App Registration a unique title.
   • Supported Account Types: Single Tenant.
   • Redirect URI (Optional):
     • Dropdown should be set to “Web”.
     • URL: https://my.oneconnect.ai or https://eu.oneconnect.ai depending on which OneConnect site you are using.
5. Click Register. The App Registration page will load. Within the Essentials section, the Application (Client) ID can be found.

Configure API Permissions

1. Once finished with setting up the Client Id, navigate to the API Permissions page (left navigation panel, beneath Manage).
2. Select Add a Permission.
   • There is a default permission for Microsoft Graph – User.Read. This is the only required permission needed.
3. In the API Permissions page, click Grant Admin consent for {Tenant Name}.
4. Click on Yes for the consent confirmation popup.

Generate a Client Secret

1. Go to Manage > Certificates and Secrets.
2. Click + New Client Secret.
3. Provide:
   • A description.
   • An Expiration period (up to 24 months).
4. Click Add.
5. Save the Client Secret Value displayed under the Value column. 

Note: Please note that this value will only appear once, it is encouraged to save this value in a secure location should you need it a second time. Otherwise, best practice is to create a whole new client secret each time one is needed.

Setting up your Service Principal in Azure DevOps

Adding Service Principal to Azure DevOps

Within your Azure DevOps Organization:

• Click on Organization Settings.
• Within the General section, select Users.
• Click on Add Users.
• In the Users or Service Principals field, select the service principle that was previously created in Entra ID.
• Access Level – Basic.
• Add the service principal to all relevant Projects within the Azure DevOps organization.
• Azure DevOps Groups – Project Administrators.
• Click Add.

Allow Permissions of Edit Process in Boards 

Once the Service Principal has been granted access to the relevant projects in Azure DevOps Organization Settings:

• Within the Security section, select Permissions. 
• Switch the view to Users.
• Select the name of the Service Principal that was added.
• Beneath the Permissions view, locate the Boards section, change the dropdown value for Edit Process to Allow.