With increasing security risks come different preferences with authenticating to different programs. OneConnect now supports multiple authentication options for clients to choose from.

URL + Personal Access Token

To authenticate to Azure DevOps, users can enter the URL of the Azure DevOps Organization, and enter a Personal Access Token (PAT).

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. 
• PAT has an expiry date. 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

Service principal based authentication with Azure DevOps  is an alternative to using Personal Access Tokens. Service principals are available to Microsoft Entra ID (formerly Azure AD) backed organizations only.

To authenticate Azure DevOps, users can enter the URL of the Azure DevOps Organization, and set up a service principal.

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).

Creating a Service Principal

There are currently two ways to set up a service principal to connect to Azure DevOps: Using an Entra application that OnePlan created or using an application that you create.

Authorize Button

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

Within the Azure DevOps connector, expand the Advanced Options section. Click on the blue Authorize button, a new window will appear requesting permissions to be granted on behalf of your organization. Click Accept and enter the tenant administrator credentials.

In Entra, a security principal will be created (in the enterprise applications section) with the name of OneConnect Azure DevOps Authentication.

The permission that is  granted is Microsoft Graph – User.Read.

Client Id and Client Secret

If you want to use your own application in Entra ID, please follow the steps below.

Only the tenant administrator may be able to create a new application in Microsoft Entra ID.

Create the App Registration within Entra

1. While logged in as a tenant admin 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.
6. Once the registration has been completed, the App Registration page will load. Within the Essentials section, the Application (Client) ID can be found.
7. On the navigation panel on the left, click on Certificates & Secrets.
8. Towards the middle-left of the page, click on + New Client Secret. The Add a Client Secret panel will expand on the right side of the browser. Note: This is where a Description and the Expiration Date can be set according to the company’s policy. Please keep note of the expiration date as the Client Secret will have to be remade once expires for the integration to work.
9. Click Add. The panel will close, and the Client Secret will be in the middle of the page underneath the column labelled as Value.

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, it is best practice to create a whole new client secret for each time it is needed.

Set API Permissions

1. Once finished with setting up the Client Secret, 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.

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.