Azure Foundry Agent OpenAPI connector: Cannot authenticate to Azure DevOps using PAT in OpenAPI spec

by

Summary

A misconfigured OpenAPI security scheme caused Azure Foundry Agent to silently drop the Authorization header when calling Azure DevOps. Although the same Personal Access Token (PAT) worked via curl, the Foundry Agent’s OpenAPI connector rejected the header because Azure DevOps PAT authentication requires HTTP Basic Auth, not an apiKey header, and Foundry Agent enforces strict security‑scheme semantics.

Root Cause

The failure stemmed from incorrect OpenAPI security configuration:

  • The spec used type: apiKey for a header named Authorization, which Foundry Agent does not treat as a valid authentication mechanism.
  • Attempts to embed a pre‑encoded Authorization header via x-default were ignored because Foundry Agent strips or overrides sensitive headers.
  • Azure DevOps requires Basic Auth with username = empty string and password = PAT, but the spec did not declare type: http with scheme: basic in a way Foundry Agent accepts.
  • Foundry Agent does not allow arbitrary Authorization headers to be passed directly from the spec for security reasons.

Key takeaway: Foundry Agent will not forward a manually‑defined Authorization header unless the security scheme is declared as a supported HTTP auth type.

Why This Happens in Real Systems

Systems that auto‑generate API clients often enforce strict rules around authentication:

  • Security schemes must match known patterns (basic, bearer, OAuth2).
  • Custom Authorization headers are blocked to prevent accidental credential leakage.
  • PATs are treated as secrets, so platforms avoid allowing them to be embedded in OpenAPI specs.
  • Basic Auth with empty username is a niche pattern that many API clients mishandle.

Real-World Impact

This misconfiguration leads to:

  • 401/403 authentication failures despite valid credentials.
  • Confusing error messages because the platform hides sensitive header details.
  • Time wasted debugging since the same request works in curl but fails in the connector.
  • Security risks if developers attempt to hardcode PATs into specs.

Example or Code (if necessary and relevant)

Below is a minimal OpenAPI snippet that correctly declares Azure DevOps PAT authentication for Foundry Agent using Basic Auth:

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

security:
  - basicAuth: []

This allows Foundry Agent to prompt for credentials and correctly send:

Authorization: Basic BASE64(:PAT)

How Senior Engineers Fix It

Experienced engineers resolve this by:

  • Using type: http + scheme: basic instead of apiKey.
  • Avoiding x-default or hardcoded headers because Foundry Agent strips them.
  • Supplying the PAT via Foundry’s credential UI, not the OpenAPI spec.
  • Validating the generated request using a proxy (e.g., Fiddler, mitmproxy) to confirm the header is sent.
  • Ensuring the server URL ends with the organization name and not a trailing slash mismatch.

Senior takeaway: The OpenAPI spec defines how to authenticate, not the secret itself.

Why Juniors Miss It

Juniors often assume:

  • Any header can be defined in OpenAPI and will be forwarded.
  • PATs behave like API keys, so apiKey auth should work.
  • Embedding Authorization in the spec is acceptable.
  • If curl works, the OpenAPI connector should behave identically.

They miss that Foundry Agent enforces strict security semantics and will not forward arbitrary sensitive headers unless the security scheme is declared using a supported authentication type.

Leave a Comment