Service Connections

ado-aw pipelines use service connections to mint Azure DevOps-scoped tokens at runtime. Scalar permissions.read / permissions.write values refer to Azure Resource Manager connections. Cross-organization repository writes use an Azure DevOps service connection backed by Entra workload identity federation.

Why service connections?

The compiled pipeline uses AzureCLI@3 to call az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798. connection-type: azureRM emits the ARM task inputs; connection-type: azureDevOps emits the Azure DevOps service-connection inputs.

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

Reusing existing connections

Existing ARM connections remain valid for scalar configuration and same-organization writes. Cross-organization repository writes require an Azure DevOps service connection; converting an ARM connection to WIF does not change its connection type.

---

Create the write service connection

The write service connection overrides $(System.AccessToken). Use an ARM connection for the existing scalar path or an Azure DevOps WIF connection for cross-organization repository writes.

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

Cross-organization Azure Repos writes

Create an Azure DevOps service connection backed by Entra workload identity federation. Add its service principal or managed identity to every target Azure DevOps organization in the same tenant and grant the required repository permissions. Then use expanded write configuration:

permissions:
  write:
    service-connection: ado-repository-writer
    connection-type: azureDevOps
    allow:
      - organization: other-org
        projects:
          - project: Other Project
            repositories: [target-repo]

repos:
  - name: Other Project/target-repo
    alias: target
    organization: other-org
    endpoint: ado-repository-writer

The repeated connection name is intentional: endpoint authenticates checkout, while permissions.write authorizes trusted Stage 3 REST writes.

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 needed for cross-project operations, cross-organization repository writes, or named attribution.

---

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	✅	✅ (configured connection identity)
Only read	✅	✅ (default System.AccessToken)
Only write	❌	✅ (configured connection 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@3
    displayName: "Test ADO token mint"
    inputs:
      connectionType: azureRM
      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@3 fails with “service connection not found”	The pipeline isn’t authorized to use the connection or connection-type does not match the server-side connection type
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