Skip to content

feat(auth): authenticate gateway-mediated application requests - #4963

Open
TaylorMutch wants to merge 10 commits into
feat/4953-authoritative-app-urls/TaylorMutchfrom
feat/4722-gateway-service-auth/TaylorMutch
Open

TaylorMutch wants to merge 10 commits into
feat/4953-authoritative-app-urls/TaylorMutchfrom
feat/4722-gateway-service-auth/TaylorMutch

Conversation

@TaylorMutch

@TaylorMutch TaylorMutch commented Oct 27, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Opt in to authentication and authorization for gateway-mediated application HTTP requests and WebSocket upgrades using enable_gateway_service_auth = true in [openshell.gateway]. The default is false, preserving existing application routing. This setting is independent of the supervisor app listener and compute driver.

Based on main at df6a799eb. Stacked on feat/4953-authoritative-app-urls/TaylorMutch.

Related Issue

Closes #4722. Part of RFC 0017.

Changes

  • Log service authentication as enabled/disabled only when gateway-mediated service routing is enabled.

  • Apply service authentication and mount /auth/services only while gateway service routing is enabled. enable_gateway_service_routing = false disables the gateway application path regardless of enable_gateway_service_auth.

  • Add enable_gateway_service_auth (default false), --enable-gateway-service-auth true, OPENSHELL_ENABLE_GATEWAY_SERVICE_AUTH=true, and Helm gatewayConfig."openshell.gateway".enable_gateway_service_auth. Explicit false overrides are supported.

  • Preserve existing forwarding, application-owned paths, headers, and cookies when service authentication is disabled.

  • Store browser application-session tokens through the credential issuer using an explicit session owner, preserving existing backend scopes, opaque handles, and expiration checks.

  • Resolve browser login origins through the gateway route index for both readable and hashed service hosts, preserving workspace authorization and the control-plane login boundary.

  • Apply gateway identity, workspace access, and forwarding role/scope authorization before upstream connection.

  • Add browser login with single-use bootstrap codes and bounded Secure/HttpOnly/SameSite=Strict host-only sessions.

  • Use configured credential storage for sessions and shared revocation across gateway replicas.

  • Separate gateway credentials from application bearer tokens/cookies, strip reserved credentials, and enforce origin/Fetch Metadata protections.

Configuration

Configuration surface Enable gateway application authentication
Gateway TOML [openshell.gateway] → enable_gateway_service_auth = true
Gateway CLI --enable-gateway-service-auth=true
Environment OPENSHELL_ENABLE_GATEWAY_SERVICE_AUTH=true
Helm values gatewayConfig."openshell.gateway".enable_gateway_service_auth: true

enable_gateway_service_auth defaults to false. Precedence is CLI > environment > TOML > default.

[openshell.gateway]
enable_gateway_service_routing = true
enable_gateway_service_auth = true
Gateway routing Service auth Gateway application behavior
Enabled (default) Disabled (default) Existing forwarding without gateway application authentication
Enabled Enabled Require configured gateway authentication and workspace authorization
Disabled Either Return 404; do not mount /auth/services

These flags are independent of supervisor.app_listener.enabled. Direct app-listener access delegates authentication to the ingress provider/application.

Release Notes

Gateway-mediated application authentication is opt-in through [openshell.gateway].enable_gateway_service_auth (default false), independently of the app listener.

Compatibility

With service authentication disabled, configuring mTLS, operator auth, or OIDC preserves existing loopback HTTP URLs. Enabling service authentication selects HTTPS when gateway TLS is configured. Direct supervisor ingress strips only the two gateway service session/login cookies; other application cookies retain their behavior.

Testing

  • Canonical Helm service-auth configuration passed the full chart/runtime-parser suite and final combined-chart tests, generated Helm docs, and Markdown lint. Tests cover the runtime default plus explicit true/false in gatewayConfig."openshell.gateway".enable_gateway_service_auth.

  • Renamed the auth setting consistently across TOML, CLI, environment, Helm, tests, man page, and docs. Standalone auth-stage server tests (2,822 passed; 51 PostgreSQL-dependent tests skipped), combined-stack server/proxy tests, strict Clippy, full Helm runtime validation, generated docs, Markdown lint, and formatting passed. Default remains false; no live E2E was rerun for this configuration-only rename.

  • Rebased all five branches onto main df6a799eb, preserving the SPIFFE provider-token limiter and application-auth peer metadata. Branch ancestry, patch scope, and frozen Python/Go SDK checks passed.

  • Standalone URL PR: 2,801 server tests (50 PostgreSQL-dependent tests skipped), 650 core tests, 336 Kubernetes-driver tests, 300 supervisor tests, and 409 CLI library tests passed.

  • Combined auth/discovery-reader/proxy stack: 2,831 server tests (51 PostgreSQL-dependent tests skipped) and all nine proxy tests passed. Strict all-target Clippy passed for server, core, Kubernetes driver, supervisor, CLI, and proxy.

  • Full Helm suites passed for the URL/Helm follow-up, including rendered TOML, resource coherence, ownership, and scaling. The combined stack passed all 500 gateway-chart unit tests. Generated Helm docs, Markdown/MDX lint, Rust formatting, and whitespace checks passed.

  • Fresh live k3d shared/push/graceful E2E passed on the rebased URL/Helm stage with matching locally built images: Pod-IP ingress without app Services, HTTP/WebSockets, Host/SNI, NetworkPolicy, withdrawal/re-exposure, takeover preserving workload identity/process/memory, and listener-disabled gateway fallback using enable_gateway_service_routing: true. The isolated release and namespace were removed.

Dedicated, poll, abrupt-loss, and external-ingress scenarios were not rerun for these review fixes. Current-head GitHub CI is pending.

Qualification limits

Live Kubernetes qualification covers dedicated/shared supervisors, graceful shared-owner replacement, gateway outage, and policy isolation. Hashed URL/public-port behavior is covered by unit tests. Whole-node failure, real network partitions, metric-driven HPA, sustained production load, external ingress/DNS automation, and published release artifacts remain unqualified. Installation-status presentation (#4670) remains separate work. The example Kubernetes HTTPRoute controller remains a separate compatibility POC.

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Relevant implementation, configuration, and API documentation updated

PR dependency order: #4956 → #4963 → #4964 → #4957.

Replaces #4959, which GitHub automatically marked merged into its former SDK base when the rebased branches were published. This draft isolates the auth change against the URL layer; main was unchanged by that event.

@copy-pr-bot

copy-pr-bot Bot commented Oct 27, 2026

Copy link
Copy Markdown

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@github-actions

Copy link
Copy Markdown

@TaylorMutch
TaylorMutch added this pull request to stack #4965 October 27, 2026 05:46
@TaylorMutch
TaylorMutch removed this pull request from stack #4965 October 27, 2026 05:47
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch from 18b394a to ce2a99e Compare October 27, 2026 06:24
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch from 2574b9a to 70e365e Compare October 27, 2026 06:24
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch from ce2a99e to de94456 Compare October 27, 2026 06:25
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch 2 times, most recently from 30cf9ce to 6b2fe9c Compare October 27, 2026 06:46
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch from de94456 to 3b08d4c Compare October 27, 2026 06:46
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch from 6b2fe9c to dae4a9d Compare October 27, 2026 21:06
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch 2 times, most recently from c35e581 to caacd27 Compare October 28, 2026 17:05
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch 2 times, most recently from 66220a7 to 3dc01d7 Compare October 28, 2026 22:52
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch 3 times, most recently from c37b455 to dd566cd Compare October 30, 2026 17:57
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch 2 times, most recently from b71991c to ad8be4d Compare October 30, 2026 18:13
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch 2 times, most recently from 00061b6 to acc3754 Compare October 30, 2026 21:11
@purp purp added topic:operability Installing/configuring deployments, upgrades, backup/restore, diagnostics, and maintenance. topic:security Vulnerability management, security analysis/auditing, bypass detection, and abuse prevention. labels Nov 15, 2026
@TaylorMutch
TaylorMutch marked this pull request as ready for review November 16, 2026 19:22
@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. api-behavior — No explicit risk acceptance found

TLS loopback gateways now advertise https:// instead of http:// when mTLS, operator authentication, or OIDC is configured, even with service_auth_enabled=false.

  • Impact: Browsers and SDK consumers following returned service URLs can fail certificate validation or lose HTTP-origin state despite unchanged configuration.
  • Action: For v0.1.9, preserve HTTP advertisement when service authentication is disabled and reserve the HTTPS switch for explicit opt-in with TLS-trust and origin-migration guidance.
  • PR: feat(auth): authenticate gateway-mediated application requests #4963

2. api-behavior — No explicit risk acceptance found

The supervisor application listener now drops every __Host-openshell-* request cookie instead of filtering only Cloudflare authentication cookies.

  • Impact: Applications using previously forwarded cookies such as __Host-openshell-app lose session state through direct supervisor ingress even with service_auth_enabled=false.
  • Action: Preserve existing application-cookie forwarding in v0.1.9 and make any new reserved-cookie filtering explicitly opt-in with documented cookie-renaming guidance.
  • PR: feat(auth): authenticate gateway-mediated application requests #4963
Review details
  • Execution: complete
  • Candidate: PR #4963 (6bb8b3d1e00438f877d8c2ed5a80ded30144903c)
  • Baseline: 433b9b936ed7e6e63a8d359cfbdad4fb41ebb0d8 (433b9b936ed7e6e63a8d359cfbdad4fb41ebb0d8)
  • Reviewed: rust-sdk, python-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch from 433b9b9 to 35e2d05 Compare November 16, 2026 19:55
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch from 5f66489 to 2bc4518 Compare November 16, 2026 19:55
@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. helm — No explicit risk acceptance found

helm upgrade --reuse-values previously accepted saved chart values but now renders service_auth_enabled = "" when the new server.serviceAuthEnabled key is absent.

  • Impact: Existing installations upgraded with --reuse-values receive invalid gateway TOML, preventing replacement gateway pods from starting even without opting into service authentication.
  • Action: For v0.1.9, default an absent server.serviceAuthEnabled to boolean false; document --set server.serviceAuthEnabled=false as an interim upgrade workaround.
  • PR: feat(auth): authenticate gateway-mediated application requests #4963
Review details
  • Execution: complete
  • Candidate: PR #4963 (a1c3d4ff983098356da4f251cf19071db98e1785)
  • Baseline: 35e2d054e2a1194e53695e449974ea34a4d5a71f (35e2d054e2a1194e53695e449974ea34a4d5a71f)
  • Reviewed: rust-sdk, python-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch from 2bc4518 to f79878c Compare November 16, 2026 21:48
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch from 35e2d05 to c503a94 Compare November 16, 2026 21:48
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch 4 times, most recently from e5927f4 to dfa898d Compare November 18, 2026 05:50
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch from b7042a9 to 1e069a1 Compare November 18, 2026 05:51
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch from dfa898d to c02b593 Compare November 18, 2026 20:14
@TaylorMutch

Copy link
Copy Markdown
Collaborator Author

/ok to test c02b593

Require configured gateway authentication for application HTTP requests
and WebSocket upgrades, with or without the independent app listener.
Add browser sessions, application credential separation, shared revocation,
request authorization, documentation, and browser coverage.

Closes #4722

Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
@TaylorMutch

Copy link
Copy Markdown
Collaborator Author

/ok to test 900920c

@TaylorMutch

Copy link
Copy Markdown
Collaborator Author

/ok to test 240aa0f

Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
@TaylorMutch

Copy link
Copy Markdown
Collaborator Author

/ok to test 1f856fa

@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. api-behavior — No explicit risk acceptance found

The supervisor application listener previously forwarded __Host-openshell-service-session and __Host-openshell-service-login cookies but now strips both unconditionally.

  • Impact: Existing direct-ingress applications using either previously unreserved cookie name lose session or login state even with enable_gateway_service_auth=false.
  • Action: Preserve existing direct-ingress cookie forwarding in v0.1.10, and introduce these reserved names only through explicit opt-in with cookie-renaming migration guidance.
  • PR: feat(auth): authenticate gateway-mediated application requests #4963
Review details
  • Execution: complete
  • Candidate: PR #4963 (818b4bd895b96dbdf2e47f6e6ff6199609c98697)
  • Baseline: f8d1af1111c4aca5207127d501a11362865759d6 (f8d1af1111c4aca5207127d501a11362865759d6)
  • Reviewed: rust-sdk, python-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:enterprise Authentication, multitenancy, gateway interceptors, FIPS, and enterprise requirements. topic:authnz Authentication, authorization, identity, sessions, credential protection, and policy integrity. topic:documentation Architecture docs, READMEs, project website updates, and automated documentation generation. topic:operability Installing/configuring deployments, upgrades, backup/restore, diagnostics, and maintenance. topic:security Vulnerability management, security analysis/auditing, bypass detection, and abuse prevention.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants