Support engine.auth for Azure OpenAI OIDC authentication

[lpcox]

Problem

Users configuring Azure OpenAI with GitHub OIDC authentication get a schema validation error at compile time:

error: Unknown property: auth. Did you mean 'path'? It belongs under 'cache' or 'imports'

The intended workflow frontmatter:

permissions:
  id-token: write

engine:
  env:
    COPILOT_PROVIDER_BASE_URL: https://my-resource.openai.azure.com
    COPILOT_PROVIDER_TYPE: azure
    COPILOT_MODEL: gpt-4.1
  auth:
    type: github-oidc
    audience: https://cognitiveservices.azure.com

Expected Behavior

gh-aw should:

1. Accept engine.auth in the workflow schema
2. Map engine.auth fields to AWF environment variables in the generated AWF config
3. Pass the auth configuration through to the API proxy sidecar

AWF Already Supports This

The AWF firewall (github/gh-aw-firewall) has full OIDC support. The API proxy sidecar reads the following environment variables and uses them to exchange GitHub OIDC tokens for Azure AD/Entra tokens:

AWF env var	Maps from engine.auth
AWF_AUTH_TYPE	auth.type (e.g. github-oidc)
AWF_AUTH_OIDC_AUDIENCE	auth.audience
AWF_AUTH_AZURE_TENANT_ID	auth.azure-tenant-id (optional)
AWF_AUTH_AZURE_CLIENT_ID	auth.azure-client-id (optional)
AWF_AUTH_AZURE_SCOPE	auth.azure-scope (optional, default: https://cognitiveservices.azure.com/.default)
AWF_AUTH_AZURE_CLOUD	auth.azure-cloud (optional)

The sidecar's OpenAI provider (containers/api-proxy/providers/openai.js) already handles the full OIDC flow:

1. Exchanges GitHub OIDC token for Azure AD token via federated credential
2. Injects Authorization: Bearer <azure-token> on upstream requests
3. Handles token refresh automatically

AWF source references

• src/services/api-proxy-service.ts:115-126 — OIDC env vars forwarded to sidecar
• containers/api-proxy/providers/openai.js:39-59 — OIDC token provider initialization
• containers/api-proxy/oidc-token-provider.js — Full OIDC ↔ Azure AD token exchange

Suggested Implementation

1. Add auth to the engine schema in pkg/parser/schemas/main_workflow_schema.json
2. In the AWF config builder (pkg/workflow/awf_config.go), map engine.auth fields to AWF_AUTH_* env vars in the generated config
3. Ensure permissions: id-token: write is validated when auth.type: github-oidc is used

[lpcox]

Workaround: Use engine.env to pass OIDC auth config

Until engine.auth is supported in the schema, you can pass the AWF auth environment variables directly via engine.env:

permissions:
  id-token: write

engine:
  env:
    COPILOT_PROVIDER_BASE_URL: https://my-resource.openai.azure.com
    COPILOT_PROVIDER_TYPE: azure
    COPILOT_MODEL: gpt-4.1
    AWF_AUTH_TYPE: github-oidc
    AWF_AUTH_OIDC_AUDIENCE: https://cognitiveservices.azure.com

Full mapping from proposed engine.auth → AWF_AUTH_* env vars

engine.auth field	Environment variable	Required	Default
type: github-oidc	AWF_AUTH_TYPE=github-oidc	✅	—
audience	AWF_AUTH_OIDC_AUDIENCE	No	api://AzureADTokenExchange
azure-tenant-id	AWF_AUTH_AZURE_TENANT_ID	No*	—
azure-client-id	AWF_AUTH_AZURE_CLIENT_ID	No*	—
azure-scope	AWF_AUTH_AZURE_SCOPE	No	https://cognitiveservices.azure.com/.default
azure-cloud	AWF_AUTH_AZURE_CLOUD	No	public

* azure-tenant-id and azure-client-id are required for Azure AD federated credential exchange but optional if using managed identity.

How it works

1. AWF forwards these env vars to the API proxy sidecar
2. The sidecar's OpenAI provider exchanges the GitHub OIDC token for an Azure AD/Entra token
3. The Azure AD token is injected as Authorization: Bearer <token> on upstream requests to your Azure OpenAI endpoint
4. Token refresh is handled automatically

Important

• permissions: id-token: write is required — the Actions runner needs this to mint OIDC tokens
• The sidecar needs ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN (auto-injected by the runner when id-token: write is granted; AWF forwards them when AWF_AUTH_TYPE=github-oidc)

See AWF API proxy sidecar OIDC docs for full details.