# Connect Azure DevOps

Connect Azure DevOps Boards to Neo.Tax over Microsoft OAuth, using a user that can read the projects you want analyzed. Neo.Tax only requests read access.

To connect Azure DevOps via API, you will integrate using oAuth.

Once the prerequisites below are in place, linking takes about five minutes.

#### Before you start

- **Azure DevOps Services (cloud) only.** Your organization lives at `dev.azure.com/<org>` or `<org>.visualstudio.com`. Azure DevOps Server (on-premises) can't connect over OAuth; export your work items and upload them instead.
- **Your Azure DevOps organization must be connected to Microsoft Entra ID.** Check under **Organization settings → General → Microsoft Entra**. The linking user signs in with a work account from that Entra tenant. Personal Microsoft accounts (for example `@outlook.com`) can't be used.
- **Pick the linking user. We recommend a dedicated service account that is an Azure DevOps admin** (see Step 1, Option A). Neo.Tax sees exactly what this user can see in Azure DevOps, nothing more. Using a service account (for example `neo-tax-integration@yourcompany.com`) rather than a person means the connection doesn't break when someone changes roles or leaves.
- **Find out whether users in your tenant can approve apps themselves.** Many companies require an Entra admin to approve new apps. If yours does, you'll need a **Global Administrator**, **Cloud Application Administrator**, or **Application Administrator** for Step 2. This is a Microsoft Entra admin, which is a different role from the Azure DevOps admin in Step 1.

#### Step 1: Give the linking user read access in Azure DevOps

> **Note:** **Two different admin roles come up in this article.** An **Azure DevOps admin** (Project Collection Administrator, this step) controls what the linking user can see in Azure DevOps. A **Microsoft Entra admin** (Step 2) approves the Neo.Tax app for your company's Microsoft sign-in. They are separate roles, often held by different people, and you may need both.

First, in Azure DevOps, go to **Organization settings → Users** and add the linking user (or confirm they're already there) with the **Basic** access level. Then choose one of the options below.

**Option A: Make the linking user an Azure DevOps admin (recommended)**

Best if you have many projects. The user can see every project in the organization, including projects created later, so you never have to grant access project by project.

1. Go to **Organization settings → Permissions**.
1. Select **Project Collection Administrators**, open **Members**, and add the linking user.

Neo.Tax still only gets read access. The permissions you approve in Step 3 are read-only, so the admin role widens what Neo.Tax can *see*, not what it can *do*. Because the service account itself is now an admin, protect its sign-in like any other admin account (for example, with MFA and Conditional Access).

**Option B: Give the linking user Readers access to each project**

Use this if your security policy doesn't allow an admin service account, or if you want Neo.Tax to see only some projects. Only do this if you need to exclude non-technology projects like HR, Marketing. NeoTax can only evaluate R&D/capitalizable work from the projects it sees.

Add the user to the **Readers** group in every project you want analyzed, and leave out projects that have nothing to do with R&D or ASC 350-40.

- **One project at a time:** open the project, go to **Project settings → Permissions**, select the **Readers** group, open **Members**, and add the linking user.
- **Many projects at once, in the browser:** if the linking user is new to your organization, add them from **Organization settings → Users → Add users**. Select every project you want under **Add to projects**, and choose **Project Readers** under **Azure DevOps Groups**.
- **Many projects at once, from the command line:** with the [Azure DevOps CLI](https://learn.microsoft.com/en-us/azure/devops/cli/) installed and signed in as an admin, this adds the linking user to the Readers group of every project. Replace the organization URL and email first.

```bash
ORG=https://dev.azure.com/your-org
USER=neo-tax-integration@yourcompany.com
az devops project list --org $ORG --query "value[].name" -o tsv | while read -r PROJECT; do
  GROUP=$(az devops security group list --org $ORG --project "$PROJECT" --query "graphGroups[?displayName=='Readers'].descriptor | [0]" -o tsv)
  az devops security group membership add --org $ORG --group-id "$GROUP" --member-id "$USER"
done
```

With Option B, projects created after you connect aren't included automatically. Add the linking user to each new project's Readers group.

**Area paths (only if you restrict them)**

If your projects limit who can see work items under certain area paths, go to **Project settings → Boards → Project configuration → Areas**, open **Security** on each area, and confirm **View work items in this node** is set to **Allow** for the linking user.

#### Step 2: Make sure Microsoft will let the consent through

If users in your tenant can approve apps themselves, skip to Step 3.

Otherwise, the linking user will see **Approval required** or **Need admin approval** when they try to accept. An Entra admin needs to approve the app for your organization *before* the linking user does Step 3. Approving the app doesn't connect the admin's own account; the connection always belongs to whoever signs in during Step 3. Use one of these:

- **Option A: The admin approves it with a consent link.** 

  - NeoTax [consent link.](https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=e60995aa-9afd-47d7-87f6-249c18909119&scope=499b84ac-1321-427f-aa17-267ca6975798%2F.default&redirect_uri=https%3A%2F%2Fapp.merge.dev%2Foauth%2Fcallback)
  - Your Entra admin opens this, reviews the permissions, and clicks **Accept**, which approves the app for everyone in your organization. If someone has already tried to connect, the admin can instead go to **Microsoft Entra admin center → Enterprise applications → Neo.Tax Azure DevOps Integration → Permissions** and click **Grant admin consent**. Then the linking user does Step 3.
  - Note: it may show an error on redirect at the end of the flow, but should still succeed.
- **Option B: The user requests approval.** If your organization has the admin consent workflow turned on, the linking user can submit an approval request from the consent screen. An Entra admin approves it in **Microsoft Entra admin center → Enterprise applications → Admin consent requests**. Then the linking user repeats Step 3. If the consent screen doesn't offer a way to request approval, use Option A.

If you use Conditional Access policies that limit which apps users can sign in to, allow the **Neo.Tax Azure DevOps Integration** enterprise application.

#### Step 3: Connect Azure DevOps in Neo.Tax

> **Warning:** **Confirm you're signed in to the right Microsoft account in your browser before you start.** The account you sign in with here is the one Neo.Tax will use. A private or incognito window avoids picking up the wrong account.

1. Go to the link provided to you by your NeoTax implementation team.
1. Select **Azure DevOps**.
1. Follow the directions in the modal. If asked for your organization, enter the name that appears after `dev.azure.com/`.
1. When Microsoft asks you to sign in, sign in as the linking user from Step 1.
1. Review the permissions on the Microsoft consent screen and click **Accept**. You should see only these:

| What the screen says | Azure DevOps scope | Why Neo.Tax needs it |
| --- | --- | --- |
| Work items (read) | `vso.work` | Read work items (your tickets) and their metadata. |
| Project and team (read) | `vso.project` | List your projects and teams so work can be organized by team. |
| User profile (read) | `vso.profile` | Find the organizations and projects the linking user can access. |
| Analytics (read) | `vso.analytics` | Query Azure DevOps Analytics reporting data about your work items. |
| Maintain access to data you have given it access to | `offline_access` | Keep syncing without someone signing in again each time. |
| View your basic profile | `openid`, `profile` | Sign-in only. |

> **Tip:** **Neo.Tax uses only read access, and does not request write access.** 

1. When you see the success message, click **Done**.

<div class="notion-gap" aria-hidden="true"></div>

#### Troubleshooting

**"Approval required" or "Need admin approval".** Your tenant requires an admin to approve new apps. See Step 2.

**"User account does not exist in tenant" (AADSTS50020) or a similar sign-in error.** You signed in with a personal Microsoft account, or with an account from a different tenant than the one connected to your Azure DevOps organization. Sign out and sign in with your work account.

**The connection worked, but some projects or work items are missing.** The linking user can't see them. If you used Option B, add the user to the **Readers** group in those projects, including any created after you connected. With either option, check area path permissions (Step 1). The next sync picks them up.

**I'm seeing an error about third-party cookies, but I have cookies enabled.** Try Chrome instead of Safari.

**The connection worked, then stopped.** The linking user was probably removed from the Azure DevOps organization, lost their access level or their Project Collection Administrators or Readers membership, or had the app's consent revoked. Restore their access, then reconnect.

#### FAQ

**Q: What data does Neo.Tax read from Azure DevOps?**

A: Neo.Tax has *read-only* access to these objects and fields:

| Work items | Users | Projects and teams |
| --- | --- | --- |
| *Title<br>Description<br>Work item ID<br>Work item type<br>State<br>Assigned to<br>Created by<br>Parent work item<br>Project<br>Priority<br>Tags<br>Due date<br>Created date<br>Changed date<br>Closed date<br>Work item URL* | *Name<br>Email address<br>Is active<br>User ID* | *Name<br>Identifier<br>Team members* |

**Q: Does Neo.Tax see our source code, pipelines, or test plans?**

A: No. Neo.Tax doesn't request the Code, Build, Release, or Test scopes, so it can't read repositories, pipelines, or test data.

**Q: Can Neo.Tax change anything in Azure DevOps?**

A: No. Every Azure DevOps permission Neo.Tax requests is read-only.

**Q: Does my Azure DevOps need to be set up in a particular way?**

A: No. Neo.Tax ingests work items whatever process template you use (Agile, Scrum, CMMI, Basic, or custom), then groups them into higher-level projects using AI and any hierarchy you already have, like Epics and Features.

**Q: Can I use Azure DevOps alongside GitHub or Jira?**

A: Yes. This works best when different teams use different systems. We usually recommend starting with your most widely used system, then adding the second if there are coverage gaps. Your implementation team will help you decide.

**Q: We have more than one Azure DevOps organization. Can we connect all of them?**

A: Talk to your implementation team. Each organization is a separate connection.
