Skip to content

docs: update authentication and API proxy guidance - #6889

Merged
lpcox merged 6 commits into
mainfrom
update-auth-proxy-docs
Aug 3, 2026
Merged

docs: update authentication and API proxy guidance#6889
lpcox merged 6 commits into
mainfrom
update-auth-proxy-docs

Conversation

@lpcox

@lpcox lpcox commented Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • align auth documentation with the always-on, five-provider API proxy implementation
  • document current OpenAI, Azure, Anthropic, Copilot, Gemini, and Vertex authentication behavior
  • correct OIDC examples, enterprise Copilot semantics, provider URLs, and credential-isolation details
  • explicitly document the missing AWS SigV4 request signing and Anthropic WIF beta-header compatibility risk

Validation

  • Markdown lint passes for all three updated files
  • documentation site builds successfully
  • git diff --check passes

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 01b67b6c-fcd9-4c60-8409-827495c49557
Copilot AI review requested due to automatic review settings August 3, 2026 16:09
@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Documentation Preview

Documentation build failed for this PR. View logs.

Built from commit 86174d2

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates authentication documentation to reflect the always-on, five-provider API proxy and current credential flows.

Changes:

  • Expands provider and OIDC authentication guidance.
  • Documents credential placeholders and known AWS/Anthropic limitations.
  • Updates CLI examples and provider configuration references.
Show a summary per file
File Description
docs/authentication-architecture.md Updates architecture, providers, and OIDC behavior.
docs/auth-matrix.md Expands the provider authentication matrix.
docs/api-proxy-sidecar.md Revises setup, configuration, and OIDC examples.

Review details

Tip

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

Suppressed comments (3)

docs/api-proxy-sidecar.md:800

  • As in the Azure example, preserving ACTIONS_ID_TOKEN_REQUEST_* causes passthroughHostEnvironment() to copy the OIDC request capability into the agent (src/services/agent-environment/env-passthrough.ts:36-65). That conflicts with this guide's credential-isolation model. Isolate these variables from the agent or clearly disclose that the agent currently receives them.
          sudo --preserve-env=AWF_AUTH_TYPE,AWF_AUTH_PROVIDER,AWF_AUTH_GCP_WORKLOAD_IDENTITY_PROVIDER,AWF_AUTH_GCP_SERVICE_ACCOUNT,OPENAI_API_TARGET,OPENAI_API_BASE_PATH,ACTIONS_ID_TOKEN_REQUEST_URL,ACTIONS_ID_TOKEN_REQUEST_TOKEN \

docs/api-proxy-sidecar.md:801

  • The GCP exchange can initialize in the sidecar, but this command still does not route the agent through the OpenAI adapter. buildOpenAiCredentialEnv() only adds OPENAI_BASE_URL when openaiApiKey exists (src/services/credentials/openai-credential-env.ts:20-31); OIDC configuration alone leaves the agent env unchanged. Please implement OIDC-triggered OpenAI routing before documenting this invocation as functional.
            awf --openai-api-target aiplatform.googleapis.com \

docs/api-proxy-sidecar.md:856

  • This third OIDC example has the same credential-isolation conflict: preserving ACTIONS_ID_TOKEN_REQUEST_* makes the current agent environment builder forward both values to agent code. Since those values authorize minting a GitHub OIDC JWT, they are not merely harmless routing metadata. Exclude them from the agent or document the exposure.
          sudo --preserve-env=AWF_AUTH_TYPE,AWF_AUTH_PROVIDER,AWF_AUTH_ANTHROPIC_FEDERATION_RULE_ID,AWF_AUTH_ANTHROPIC_ORGANIZATION_ID,AWF_AUTH_ANTHROPIC_SERVICE_ACCOUNT_ID,AWF_AUTH_ANTHROPIC_WORKSPACE_ID,ACTIONS_ID_TOKEN_REQUEST_URL,ACTIONS_ID_TOKEN_REQUEST_TOKEN \
  • Files reviewed: 3/3 changed files
  • Comments generated: 5
  • Review effort level: Balanced

Comment thread docs/authentication-architecture.md Outdated
Comment thread docs/api-proxy-sidecar.md Outdated
Comment thread docs/authentication-architecture.md Outdated
Comment thread docs/api-proxy-sidecar.md Outdated
Comment thread docs/api-proxy-sidecar.md Outdated
* fix: add Anthropic WIF beta headers

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 1bc91d4c-0fdf-40ff-94e6-250d18f08563

* fix: apply WIF beta headers unconditionally in _exchangeForAnthropicToken

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Copilot-Session: 1bc91d4c-0fdf-40ff-94e6-250d18f08563
@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

✅ Copilot review passed with no inline comments.

@lpcox Add the ready-for-aw label to this PR to trigger agentic CI smoke tests.

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

✅ Coverage Check Passed

Overall Coverage

Metric Base PR Delta
Lines 98.94% 98.97% 📈 +0.03%
Statements 98.83% 98.85% 📈 +0.02%
Functions 99.19% 99.19% ➡️ +0.00%
Branches 95.15% 95.15% ➡️ +0.00%
📁 Per-file Coverage Changes (1 files)
File Lines (Before → After) Statements (Before → After)
src/log-directory-setup.ts 96.2% → 100.0% (+3.78%) 96.3% → 100.0% (+3.71%)

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

lpcox added 2 commits August 3, 2026 09:57
* feat: sign AWS Bedrock requests with SigV4

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 60f8a12a-5b5b-41d6-8cce-35c71f8c2ac5

* fix: reframe rewritten fallback requests

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 60f8a12a-5b5b-41d6-8cce-35c71f8c2ac5

---------

Copilot-Session: 60f8a12a-5b5b-41d6-8cce-35c71f8c2ac5
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 01b67b6c-fcd9-4c60-8409-827495c49557
* fix: isolate Actions OIDC from agent

Keep GitHub Actions OIDC request credentials in the API proxy sidecar.
Prevent default, env-all, env-file, and explicit environment paths from
exposing them to untrusted agent code.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 01b67b6c-fcd9-4c60-8409-827495c49557

* docs: clarify OIDC agent credential boundary

* docs: align OIDC isolation with MCP gateway

Describe the runner-owned gateway flow generated by gh-aw and add direct
regression coverage for env-file credential exclusion.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 01b67b6c-fcd9-4c60-8409-827495c49557

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Copilot-Session: 01b67b6c-fcd9-4c60-8409-827495c49557
@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Smoke Copilot BYOK AOAI (Entra) completed. Copilot AOAI BYOK (Entra) mode operational. 🔓

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

📰 VERDICT: Smoke Docker Sbx has concluded. All systems operational. This is a developing story. 🎤

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

📡 Smoke OTel Tracing completed. All tracing scenarios validated. ✅

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Smoke Copilot BYOK completed. Copilot BYOK mode operational. 🔓

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

🛡️ Smoke Copilot Network Isolation confirmed the egress allowlist is enforced. ✅

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Contribution Check failed. Please review the logs for details.

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Smoke Claude passed

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Security Guard failed. Please review the logs for details.

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

🔌 Smoke Services — All services reachable! ✅

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

✨ The prophecy is fulfilled... Smoke Codex has completed its mystical journey. The stars align. 🌟

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

📰 VERDICT: Smoke Copilot has concluded. All systems operational. This is a developing story. 🎤

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Smoke Gemini completed. All facets verified. 💎

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Smoke Copilot BYOK AOAI (api-key) completed. Copilot AOAI BYOK (api-key) mode operational. 🔓

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Chroot tests passed! Smoke Chroot - All security and functionality tests succeeded.

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Build Test Suite completed successfully!

@github-actions github-actions Bot added the smoke-copilot-network-isolation Copilot network-isolation egress smoke test label Aug 3, 2026
@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

EGRESS_RESULT allow=pass deny=pass

✅ allowed domain (github.com) reachable: allowed=200
✅ blocked domain (example.com) denied: CONNECT tunnel failed (403)

Overall status: PASS

cc @lpcox

Warning

Firewall blocked 1 domain

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

  • example.com

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

network:
  allowed:
    - defaults
    - "example.com"

See Network Configuration for more information.

🛡️ Egress verdict from Smoke Copilot Network Isolation
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Smoke Test: Copilot BYOK (Direct Mode) — PASS

  • ✅ GitHub.com connectivity: HTTP 200
  • ✅ File write/read: Verified
  • ✅ BYOK inference: Working (api-proxy → api.githubcopilot.com)
  • ✅ GitHub MCP: Functional

Running in direct BYOK mode via COPILOT_PROVIDER_API_KEY

🔑 BYOK report filed by Smoke Copilot BYOK
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Smoke Test: Claude Engine Validation

Check Result
API status ✅ PASS
GH check ✅ PASS
File status ✅ PASS

Overall result: PASS

Generated by Smoke Claude for #6889 · haiku45 · 55.9 AIC · ⊞ 3.6K ·
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Smoke Test: Copilot Engine Validation

Overall: PASS

cc @lpcox

📰 BREAKING: Report filed by Smoke Copilot
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Smoke Test Results

  • GitHub MCP Testing: ❌ (Access filtered by secrecy policy)
  • GitHub.com Connectivity: ❌ (Connection failed)
  • File Writing Testing: ✅ (Success)
  • Bash Tool Testing: ✅ (Success)

Overall Status: FAIL

💎 Faceted by Smoke Gemini
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Smoke Test: GitHub Actions Services Connectivity

  • Redis PING: ❌ (Temporary failure in name resolution)
  • PostgreSQL pg_isready: ❌ (no response)
  • PostgreSQL SELECT 1: ❌ (could not translate host name)

Overall: FAILhost.docker.internal could not be resolved from the AWF sandbox.

🔌 Service connectivity validated by Smoke Services
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Merged PRs:

Checks:

  • ✅ GitHub PR queries
  • ✅ Playwright GitHub title check
  • ✅ Smoke file write/read
  • ✅ Discussion lookup
  • ✅ Build (npm ci && npm run build)

Overall: PASS

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
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

fix: isolate Actions OIDC from agent container ✅
feat: sign AWS Bedrock requests with SigV4 ✅
GitHub.com connectivity (HTTP 200) ✅
File write/read test ✅
BYOK inference test ✅
Running in direct BYOK mode (AWF_AUTH_TYPE=github-oidc + AWF_AUTH_AZURE_* + COPILOT_PROVIDER_BASE_URL) via api-proxy → Azure OpenAI (Foundry, o4-mini-aw) authenticated via Microsoft Entra
Overall status: PASS
cc @lpcox

🪪 BYOK (AOAI Entra) report filed by Smoke Copilot BYOK AOAI (Entra)
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Smoke Test: OTel Tracing — All Scenarios Passed ✅

  • Scenario 1 (Module load):otel.js loaded, isEnabled: true, exports startRequestSpan, setTokenAttributes, setBudgetAttributes, endSpan, endSpanError, shutdown, isEnabled + internals.
  • Scenario 2 (Test suite): ✅ 59/59 tests passed (2 suites: otel.test.js, otel-fanout.test.js).
  • Scenario 3 (Env var forwarding):env-passthrough.ts forwards GITHUB_AW_OTEL_TRACE_ID/GITHUB_AW_OTEL_PARENT_SPAN_ID; api-proxy-env-config.ts forwards GH_AW_OTLP_ENDPOINTS, OTEL_EXPORTER_OTLP_ENDPOINT, plus trace context.
  • Scenario 4 (Token tracker hook):onUsage callback present in token-tracker-http.js (4 occurrences).
  • Scenario 5 (OTEL diagnostics): ✅ Spans exported to otel.jsonl for this run, including a valid gh-aw.agent.setup span with correct resource/trace attributes.

Overall: PASS — no failures detected.

📡 OTel tracing validated by Smoke OTel Tracing
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Smoke Test Copilot BYOK (Direct)

  • GitHub MCP PR list: ❌ (MCP error: inaccessible)
  • github.com HTTP: ✅
  • File I/O: ✅
  • Direct BYOK inference: ✅

Running in direct BYOK mode (COPILOT_PROVIDER_API_KEY + COPILOT_PROVIDER_BASE_URL) via api-proxy → Azure OpenAI (Foundry, o4-mini-aw)

@lpcox Status: FAIL

🔑 BYOK (AOAI api-key) report filed by Smoke Copilot BYOK AOAI (api-key)
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Chroot Version Comparison Results

Runtime Host Version Chroot Version Match?
Python Python 3.12.13 Python 3.12.13 ✅ YES
Node.js v24.18.0 v22.23.1 ❌ NO
Go go1.22.12 go1.22.12 ✅ YES

Overall: FAILED — Node.js version differs between host and chroot environments. The smoke-chroot label was not added since not all tests passed.

Tested by Smoke Chroot
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

🏗️ 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 (ran successfully) ✅ PASS
.NET json-parse N/A (ran successfully) ✅ PASS
Go color ok ✅ PASS
Go env ok ✅ PASS
Go uuid ok ✅ PASS
Java gson 1/1 passed ✅ PASS
Java caffeine 1/1 passed ✅ PASS
Node.js clsx All tests passed ✅ PASS
Node.js execa All tests passed ✅ PASS
Node.js p-limit All tests passed ✅ PASS
Rust fd 1/1 passed ✅ PASS
Rust zoxide 1/1 passed ✅ PASS

Overall: 8/8 ecosystems passed — PASS

Notes:

  • All repositories cloned successfully.
  • Java builds initially failed with Could not create local repository at /home/runner/.m2/repository (root-owned directory in the sandbox environment). Retried with an explicit writable -Dmaven.repo.local path and both Java projects then compiled and passed tests successfully via the Squid proxy (squid-proxy:3128).
  • No other failures encountered.

Generated by Build Test Suite for #6889 · auto · 68.4 AIC · ⊞ 11.5K ·
Add label ready-for-aw to run again

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Smoke Test: Docker Sbx — cc @lpcox

Overall: PASS

📰 BREAKING: Report filed by Smoke Docker Sbx
Add label ready-for-aw to run again

Resolve GHSA-rgw5-rvv9-x895 in the main package dependency tree.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 01b67b6c-fcd9-4c60-8409-827495c49557
@lpcox lpcox removed the ready-for-aw label Aug 3, 2026
@lpcox
lpcox merged commit 6dbec0d into main Aug 3, 2026
27 of 28 checks passed
@lpcox
lpcox deleted the update-auth-proxy-docs branch August 3, 2026 19:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants