docs: add apiProxy.auth OIDC configuration to spec and schema by lpcox · Pull Request #2772 · github/gh-aw-firewall

lpcox · 2026-05-08T22:37:44Z

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"
    }
  }
}

Add §9.5 OIDC Authentication to awf-config-spec.md documenting the apiProxy.auth configuration object and its mapping to AWF_AUTH_* environment variables for GitHub OIDC → Azure AD/Entra token exchange. Add apiProxy.auth object to both docs/awf-config.schema.json and src/awf-config-schema.json with properties: type (github-oidc), oidcAudience, azureTenantId, azureClientId, azureScope, azureCloud. Add CLI mapping entries for all apiProxy.auth.* paths (config-only). Add api-proxy-sidecar.md to informative references. Relates to github/gh-aw#31099. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-05-08T22:38:28Z

Documentation Preview

Documentation build failed for this PR. View logs.

Built from commit 9615fe9

github-actions · 2026-05-08T22:39:01Z

✅ 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

+   | `apiProxy.auth.oidcAudience` | `AWF_AUTH_OIDC_AUDIENCE` | No | `api://AzureADTokenExchange` |
+   | `apiProxy.auth.azureTenantId` | `AWF_AUTH_AZURE_TENANT_ID` | No | — |
+   | `apiProxy.auth.azureClientId` | `AWF_AUTH_AZURE_CLIENT_ID` | No | — |
+   | `apiProxy.auth.azureScope` | `AWF_AUTH_AZURE_SCOPE` | No | `https://cognitiveservices.azure.com/.default` |
+   | `apiProxy.auth.azureCloud` | `AWF_AUTH_AZURE_CLOUD` | No | `public` |


+- `apiProxy.auth.type` → *(config-only; maps to `AWF_AUTH_TYPE`)*
+- `apiProxy.auth.oidcAudience` → *(config-only; maps to `AWF_AUTH_OIDC_AUDIENCE`)*
+- `apiProxy.auth.azureTenantId` → *(config-only; maps to `AWF_AUTH_AZURE_TENANT_ID`)*
+- `apiProxy.auth.azureClientId` → *(config-only; maps to `AWF_AUTH_AZURE_CLIENT_ID`)*
+- `apiProxy.auth.azureScope` → *(config-only; maps to `AWF_AUTH_AZURE_SCOPE`)*
+- `apiProxy.auth.azureCloud` → *(config-only; maps to `AWF_AUTH_AZURE_CLOUD`)*


+              "default": "public"
+            }
+          },
+          "required": ["type"]


+              "default": "public"
+            }
+          },
+          "required": ["type"]


+        "auth": {
+          "type": "object",
+          "description": "Authentication configuration for the API proxy sidecar. Enables OIDC-based credential exchange (e.g., GitHub OIDC → Azure AD/Entra for Azure OpenAI). See docs/awf-config-spec.md §9.5.",
+          "additionalProperties": false,
+          "properties": {


lpcox · 2026-05-08T22:47:07Z

@copilot address the review feedback

Copilot · 2026-05-08T22:51:08Z

@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.

Extend the OIDC authentication system to support three cloud providers (Azure, AWS, GCP) via a new apiProxy.auth.provider field. Schema & spec changes: - Add 'provider' enum field (azure|aws|gcp) with azure as default - Add AWS properties: awsRoleArn, awsRegion, awsRoleSessionName - Add GCP properties: gcpWorkloadIdentityProvider, gcpServiceAccount, gcpScope - Provider-specific OIDC audience defaults documented - Expand §9.5 with subsections for each provider (9.5.1-9.5.3) - Add CLI mapping entries for all new config paths - Both schemas kept in sync (src/ and docs/) Code changes: - Extract shared GitHub OIDC minting to github-oidc.js utility - Create aws-oidc-token-provider.js (STS AssumeRoleWithWebIdentity) - Create gcp-oidc-token-provider.js (STS + optional SA impersonation) - Update openai.js adapter to select provider via AWF_AUTH_PROVIDER - Update server.js to initialize/shutdown AWS OIDC providers - Forward new AWF_AUTH_* env vars in api-proxy-service.ts Note: AWS Bedrock uses SigV4 request signing (not Bearer tokens). The credential acquisition is complete; SigV4 request signing integration with server.js proxy pipeline is a follow-up. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

lpcox · 2026-05-08T23:48:46Z

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

Copilot · 2026-05-08T23:55:58Z

@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 · 2026-05-09T00:24:12Z

🔬 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 · 2026-05-09T00:24:30Z

🔥 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 · 2026-05-09T00:24:42Z

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 · 2026-05-09T00:24:54Z

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 · 2026-05-09T00:25:45Z

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 · 2026-05-09T00:25:54Z

🏗️ 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 · 2026-05-09T00:26:28Z

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

Copilot AI review requested due to automatic review settings May 8, 2026 22:37

lpcox requested a review from Mossaka as a code owner May 8, 2026 22:37

Copilot started reviewing on behalf of lpcox May 8, 2026 22:38 View session