docs: add apiProxy.auth OIDC configuration to spec and schema

[lpcox]

Summary

Adds OIDC authentication configuration to the AWF config spec and JSON schemas, enabling structured configuration of GitHub OIDC token exchange for Azure AD/Entra, AWS STS, and GCP Workload Identity deployments.

Motivation

Users configuring Azure OpenAI (or AWS Bedrock / GCP) with OIDC auth currently must pass AWF_AUTH_* environment variables manually. This PR adds a structured apiProxy.auth config object so gh-aw can generate these variables from workflow frontmatter (engine.auth). See github/gh-aw#31099.

Changes

docs/awf-config-spec.md:

• Added §9.5 OIDC Authentication with normative requirements for forwarding OIDC config to the sidecar, including subsections for Azure (§9.5.1), AWS (§9.5.2), and GCP (§9.5.3)
• Added 6 CLI mapping entries for apiProxy.auth.* paths (all config-only)
• Added docs/api-proxy-sidecar.md to informative references
• Renumbered §9.5 DIFC → §9.6
• Marked provider-required fields as required in the §9.5 table

docs/awf-config.schema.json and src/awf-config-schema.json:

• Added apiProxy.auth object with properties:
  • type (enum: github-oidc, required)
  • provider (enum: azure, aws, gcp; default: azure)
  • oidcAudience (provider-specific defaults)
  • Azure: azureTenantId, azureClientId (required for azure), azureScope, azureCloud
  • AWS: awsRoleArn, awsRegion (required for aws), awsRoleSessionName
  • GCP: gcpWorkloadIdentityProvider (required for gcp), gcpServiceAccount, gcpScope
• Provider-specific required fields enforced via if/then/else conditionals

src/schema.test.ts:

• Added 13 test cases covering all three providers: valid configs, missing required fields per provider, unknown type, unknown provider, extra properties, and invalid azureCloud enum value

containers/api-proxy/aws-oidc-token-provider.test.js and containers/api-proxy/gcp-oidc-token-provider.test.js:

• Removed unused variables origAssume and origExchange flagged by CodeQL

Example config

{
  "apiProxy": {
    "enabled": true,
    "auth": {
      "type": "github-oidc",
      "provider": "azure",
      "azureTenantId": "<tenant-id>",
      "azureClientId": "<client-id>"
    }
  }
}

{
  "apiProxy": {
    "enabled": true,
    "auth": {
      "type": "github-oidc",
      "provider": "aws",
      "awsRoleArn": "arn:aws:iam::123456789012:role/my-role",
      "awsRegion": "us-east-1"
    }
  }
}

[github-actions]

Documentation Preview

Documentation build failed for this PR. View logs.

Built from commit 9615fe9

[github-actions]

✅ Coverage Check Passed

Overall Coverage

Metric	Base	PR	Delta
Lines	87.48%	87.55%	📈 +0.07%
Statements	87.44%	87.51%	📈 +0.07%
Functions	82.66%	82.66%	➡️ +0.00%
Branches	79.65%	79.69%	📈 +0.04%

📁 Per-file Coverage Changes (1 files)

File	Lines (Before → After)	Statements (Before → After)
src/container-lifecycle.ts	87.1% → 88.2% (+1.14%)	87.5% → 88.6% (+1.11%)

---

Coverage comparison generated by scripts/ci/compare-coverage.ts

[Copilot]

Pull request overview

Adds apiProxy.auth (GitHub OIDC → Azure AD/Entra exchange) to the AWF config specification and JSON schemas so OIDC auth can be represented as structured configuration alongside existing API proxy settings.

Changes:

• Extend both config schemas with apiProxy.auth (type + Azure OIDC exchange parameters).
• Add a new normative spec section for OIDC Authentication under API proxy semantics.
• Update the CLI mapping list to include apiProxy.auth.* paths as config-only mappings to AWF_AUTH_* environment variables.

Show a summary per file

File	Description
src/awf-config-schema.json	Adds apiProxy.auth schema definitions (type, audience, Azure fields) and updates env precedence wording.
docs/awf-config.schema.json	Mirrors the schema update for published/IDE validation.
docs/awf-config-spec.md	Adds normative §9.5 OIDC Authentication section and config-path → env-var mapping entries; renumbers DIFC section and updates references.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 3/3 changed files
• Comments generated: 5

[lpcox]

@copilot address the review feedback

[Copilot]

@copilot address the review feedback

Done. Addressed all review feedback in commit docs: require azureTenantId+azureClientId for github-oidc:

• azureTenantId / azureClientId required: Updated the spec table to mark both as ✅ required, removed the managed-identity exception note, and added an if/then conditional to both schemas (src/awf-config-schema.json and docs/awf-config.schema.json) so the schema enforces this for type: "github-oidc".
• Schema test coverage: Added 7 test cases to src/schema.test.ts covering a valid github-oidc config (with and without optional fields), missing azureTenantId, missing azureClientId, unknown type, extra properties, and invalid azureCloud value. All 25 tests pass.
• PR description count (7 vs 6): The PR description had an off-by-one error; the spec correctly adds 6 CLI mapping entries (type, oidcAudience, azureTenantId, azureClientId, azureScope, azureCloud). No code change was needed for this.

[lpcox]

@copilot merge main and fix this failing ci check https://github.com/github/gh-aw-firewall/actions/runs/25584201525/job/75109431547?pr=2772

[Copilot]

@copilot merge main and fix this failing ci check https://github.com/github/gh-aw-firewall/actions/runs/25584201525/job/75109431547?pr=2772

Done. Main is merged and the failing CI check is addressed:

• Merged main (resolved the environment description conflict in src/awf-config-schema.json by taking the more detailed wording from main)
• Fixed CodeQL unused variables (origAssume in aws-oidc-token-provider.test.js:87 and origExchange in gcp-oidc-token-provider.test.js:87) — both were saved but never used, so I removed the dead assignments
• Re-added if/then schema conditionals (updated for the new multi-provider structure): azure requires azureTenantId+azureClientId, aws requires awsRoleArn+awsRegion, gcp requires gcpWorkloadIdentityProvider
• Added 13 schema tests in src/schema.test.ts covering all three providers (valid configs, missing required fields, unknown type/provider, extra properties, invalid enum values)

CodeQL now reports 0 alerts on the branch.

[github-actions]

🔬 Smoke Test Results

Test	Status
GitHub MCP connectivity	✅ PR data fetched successfully
GitHub.com HTTP connectivity	❌ Template var not expanded
File write/read	❌ Template var not expanded

PR: docs: add apiProxy.auth OIDC configuration to spec and schema
Author: @lpcox | Reviewer: @Mossaka

Overall: FAIL — pre-step template variables (${{ steps.smoke-data.outputs.* }}) were not resolved before agent invocation.

📰 BREAKING: Report filed by Smoke Copilot

[github-actions]

🔥 Smoke Test: Copilot BYOK — PASS

Test	Result
GitHub MCP (list PRs)	✅
GitHub.com connectivity	✅ (pre-step)
File write/read (smoke-test-copilot-byok-25586059937.txt)	✅
BYOK inference (this response)	✅

Running in BYOK offline mode (COPILOT_OFFLINE=true) via api-proxy → api.githubcopilot.com

Overall: PASS — @lpcox / reviewer @Mossaka

🔑 BYOK report filed by Smoke Copilot BYOK

[github-actions]

Codex Smoke

PRs: docs: document effective token budget enforcement behavior; fix: align ET budget error strings with gh-aw detection patterns
GitHub PR review: ✅ | safeinputs-gh query: ❌
Playwright: ✅ | Tavily: ❌ | File/bash: ✅ | Discussion: ✅ | Build: ✅
Overall status: FAIL

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• registry.npmjs.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "registry.npmjs.org"

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex

[github-actions]

Smoke Test Results

✅ GitHub MCP Testing: Last 2 merged PRs retrieved
✅ Playwright Testing: GitHub homepage verified
✅ File Writing Testing: Test file created
✅ Bash Tool Testing: File verified

Status: PASS

💥 [THE END] — Illustrated by Smoke Claude

[github-actions]

Chroot Smoke Test Results

Runtime	Host Version	Chroot Version	Match?
Python	Python 3.12.13	Python 3.12.3	❌ NO
Node.js	v24.14.1	v20.20.2	❌ NO
Go	go1.22.12	go1.22.12	✅ YES

Overall: ❌ Not all tests passed — Python and Node.js versions differ between host and chroot.

Tested by Smoke Chroot

[github-actions]

🏗️ Build Test Suite Results

Ecosystem	Project	Build/Install	Tests	Status
Bun	elysia	✅	1/1 passed	✅ PASS
Bun	hono	✅	1/1 passed	✅ PASS
C++	fmt	✅	N/A	✅ PASS
C++	json	✅	N/A	✅ PASS
Deno	oak	N/A	1/1 passed	✅ PASS
Deno	std	N/A	1/1 passed	✅ PASS
.NET	hello-world	✅	N/A	✅ PASS
.NET	json-parse	✅	N/A	✅ PASS
Go	color	✅	1/1 passed	✅ PASS
Go	env	✅	1/1 passed	✅ PASS
Go	uuid	✅	1/1 passed	✅ PASS
Java	gson	✅	1/1 passed	✅ PASS
Java	caffeine	✅	1/1 passed	✅ PASS
Node.js	clsx	✅	all passed	✅ PASS
Node.js	execa	✅	all passed	✅ PASS
Node.js	p-limit	✅	all passed	✅ PASS
Rust	fd	✅	1/1 passed	✅ PASS
Rust	zoxide	✅	1/1 passed	✅ PASS

Overall: 8/8 ecosystems passed — ✅ PASS

Generated by Build Test Suite for issue #2772 · ● 1.8M · ◷

[github-actions]

Smoke Test Results

• ❌ Redis PING: timeout/fail — host.docker.internal:6379 unreachable
• ❌ PostgreSQL pg_isready: no response on host.docker.internal:5432
• ❌ PostgreSQL SELECT 1: timeout/fail

Overall: FAIL — host.docker.internal is not reachable from this runner environment. Service containers may not be configured or the host alias is unavailable.

🔌 Service connectivity validated by Smoke Services