Service Connections

ado-aw pipelines use Azure Resource Manager (ARM) service connections to mint Azure DevOps-scoped tokens at runtime. These tokens grant the pipeline controlled access to ADO APIs — separately for the agent (read) and the executor (write).

Why service connections?

The compiled pipeline uses the AzureCLI@2 task to call az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 — this mints a short-lived ADO token scoped to the service connection’s identity. This keeps credentials short-lived and auditable, and avoids storing long-lived PATs.

Connection	Used by	Purpose
Write (optional override)	Stage 3 — SafeOutputs executor	Override the default $(System.AccessToken) for cross-org writes or named-identity attribution
Read (optional)	Stage 1 — Agent	Query ADO APIs (work items, repos, builds)

Reusing existing connections

If your project already has ARM service connections with appropriate ADO permissions, you can reuse them — just reference their names in permissions.write / permissions.read in your agent file. Skip to Verify your connection works to confirm they’re suitable.

---

Create the write service connection

The write service connection overrides the default $(System.AccessToken) — use it when you need writes attributed to a named service principal, or for cross-org / cross-project safe outputs where the pipeline’s built-in token lacks sufficient scope.

1. Go to your Azure DevOps Project → Project Settings → Service connections

2. Click New service connection → Azure Resource Manager

3. Choose your authentication method:

   Service principal (automatic)

   The simplest option — Azure DevOps creates the app registration and credentials for you.

   • Select Service principal (automatic)
   • Choose an Azure subscription (the identity needs at least Reader on the subscription — this is only used for az login, not for ADO operations)
   • Scope to a resource group if preferred
   • Name the connection (e.g. ado-aw-write) — this is the value you’ll use in permissions.write
   • Click Save

   Azure DevOps creates an Entra ID app registration and configures everything automatically.

   Workload Identity Federation (manual)

   Secretless — no client secrets to rotate. Use this if your organization requires manual control.

   • Create an App Registration in Entra ID (note the Application ID and Tenant ID)
   • In ADO, select Workload Identity federation (manual)
   • Fill in the Subscription ID, Service Principal Id (Application ID), and Tenant ID
   • Name the connection (e.g. ado-aw-write)
   • Click Verify and save
   • Copy the generated Issuer and Subject identifier from the connection details
   • Back in Azure Portal → App Registration → Certificates & secrets → Federated credentials → Add credential with the Issuer and Subject values
   Service principal with secret (manual)

   Use if your organization doesn’t support Workload Identity Federation or automatic provisioning.

   • Create an App Registration in Entra ID (note the Application ID and Tenant ID)
   • In the App Registration → Certificates & secrets → New client secret (copy the value)
   • In ADO, select Service principal (manual)
   • Fill in the Subscription ID, Service Principal Id, Service principal key (secret), and Tenant ID
   • Name the connection (e.g. ado-aw-write)
   • Click Verify and save

   Secret rotation

   Client secrets expire. Set a reminder to rotate before expiry, or prefer Workload Identity Federation to avoid this overhead.

4. Grant ADO permissions to the service principal. The identity behind the connection needs permission to perform write operations in Azure DevOps:

   • Go to Azure DevOps Organization Settings → Users
   • Add the service principal (search by its app registration name)
   • Set access level to Basic
   • Add it to a project-level group with the permissions your safe outputs need — Contributors is sufficient for most use cases (PRs, work items, branches, tags, wiki pages)

5. Reference it in your agent front matter:

   permissions:
     write: ado-aw-write   # ← name of the service connection you created

Least privilege

Only grant the permissions your workflows actually use. If your agents only create work item comments, you don’t need full Contributor access. See Safe Outputs reference for what each tool requires.

Default executor token

The Stage 3 executor always has write access — it defaults to $(System.AccessToken) (the pipeline’s built-in OAuth token), which is sufficient for most same-project safe outputs. A permissions.write service connection is only needed for cross-org writes, cross-project operations, or when you need the action attributed to a named service principal rather than the pipeline’s build service identity.

---

Create the read service connection (optional)

If your agent needs to query Azure DevOps APIs (e.g. read work items, list PRs, fetch build results), create a second connection with read-only ADO permissions.

Follow the same steps as above, but:

• Name the connection ado-aw-read (or similar)
• In ADO, grant the service principal Readers group access (or a custom group with only read permissions)

Then reference both in your agent file:

permissions:
  read: ado-aw-read
  write: ado-aw-write

Why separate connections?

Separation ensures the Stage 1 agent — which runs untrusted AI-generated code inside an AWF sandbox — can never perform write operations, even if prompt-injected. The write token only exists in Stage 3, after detection has passed.

Permission combinations

Configuration	Agent can read ADO?	Safe outputs can write?
Both read + write	✅	✅ (ARM-minted identity)
Only read	✅	✅ (default System.AccessToken)
Only write	❌	✅ (ARM-minted identity)
Neither (default)	❌	✅ (default System.AccessToken)

---

Authorize the pipeline

On the first run, Azure DevOps will prompt you to authorize the pipeline to use the service connections. You can also pre-authorize:

1. In the service connection’s settings, go to Security
2. Under Pipeline permissions, click + and add your ado-aw pipeline (or grant access to all pipelines in the project)

---

Verify your connection works

To confirm your service connection can mint ADO tokens, create a test pipeline:

trigger: none

pool:
  vmImage: ubuntu-latest

steps:
  - task: AzureCLI@2
    displayName: "Test ADO token mint"
    inputs:
      azureSubscription: 'ado-aw-write'  # your connection name
      scriptType: 'bash'
      scriptLocation: 'inlineScript'
      inlineScript: |
        TOKEN=$(az account get-access-token \
          --resource 499b84ac-1321-427f-aa17-267ca6975798 \
          --query accessToken -o tsv)
        if [ -n "$TOKEN" ]; then
          echo "✅ Successfully minted ADO token (${#TOKEN} chars)"
        else
          echo "❌ Failed to mint ADO token"
          exit 1
        fi

If this pipeline succeeds, your connection is correctly configured for ado-aw.

---

Troubleshooting

Symptom	Likely cause
AzureCLI@2 fails with “service connection not found”	The pipeline isn’t authorized to use the connection — check pipeline permissions in the connection’s Security tab
Token mints but safe outputs return 401/403	The service principal doesn’t have sufficient ADO permissions — verify its group membership in ADO Organization Settings → Users
”AADSTS700024: Client assertion is not within its valid time range”	Federated credential issuer/subject mismatch — regenerate in the App Registration
Same-project safe-output writes return 403 with TF401027: ... 'PullRequestContribute'	You’re on the default $(System.AccessToken) and the underlying build identity lacks PR-contribute (or has an explicit Deny) on the target repo. See the dedicated Safe-output 401/403 errors page for the diagnosis flow and three fix paths.
Cross-project safe-output writes fail with 403 even though default executor token usually works	The pipeline setting “Limit job authorization scope to current project” is restricting $(System.AccessToken). Either disable it (broader scope) or set permissions.write to an ARM SC with explicit cross-project rights