Summary
Refactor external-domains.md to document a vendor-neutral Trusted Proxy Identity architecture and establish the foundation for a future cross-platform middleware ecosystem.
The documentation should teach how applications securely consume identity from reverse proxies, ingress controllers, API gateways, and identity-aware proxies without coupling applications to a specific vendor or authentication platform.
This work should also introduce a proposed middleware abstraction that could eventually become:
- @mieweb/trusted-proxy-auth (Node.js)
- trusted-proxy-auth (Python)
The goal is to define a portable authentication contract between infrastructure and applications.
⸻
Problem
Modern applications are frequently deployed behind:
- Reverse proxies
- API gateways
- Ingress controllers
- Identity-aware proxies
- Zero Trust access systems
- External authorization services
Examples include:
- OAuth2 Proxy
- Pomerium
- Envoy ext_authz
- Traefik ForwardAuth
- NGINX auth_request
- Cloudflare Access
- Enterprise authentication gateways
- Custom internal authentication services
All of these products ultimately solve the same problem:
User
↓
Authentication Layer
↓
Application
However, applications currently lack a common, vendor-neutral way to consume verified identity.
Most implementations today fall into one of two categories:
- Vendor-specific integrations.
- Custom middleware built from generic JWT libraries.
As a result, developers repeatedly implement:
- header extraction
- JWT validation
- issuer validation
- audience validation
- expiration validation
- claim mapping
- authorization context creation
- error handling
This duplication creates:
- inconsistent implementations
- increased security risk
- unnecessary vendor coupling
- poor portability between infrastructure providers
⸻
Documentation Goals
Introduce Trusted Proxy Identity
Add documentation describing:
- Forward Auth
- External Authorization
- Identity-Aware Proxies (IAP)
- Trusted Proxy Identity
- Signed Identity Assertions
Describe the recommended request flow:
User
↓
Identity-Aware Proxy
↓
Signed Identity Assertion
↓
Application
The application should consume identity, not perform primary authentication.
⸻
Security Model
Add explicit guidance that applications SHOULD NOT trust:
- X-Forwarded-User
- X-User
- Remote-User
- X-Email
- arbitrary identity headers
- client-supplied identity claims
unless they are validated through an established trust boundary.
Document recommended trust mechanisms:
- Signed JWT/JWS assertions
- mTLS between proxy and application
- Request-signing systems
- Private networking combined with assertion validation
⸻
Preferred MVP Architecture
Document the preferred architecture:
- Proxy authenticates user.
- Proxy obtains or generates signed identity assertion.
- Proxy forwards assertion to application.
- Application validates:
- signature
- issuer
- audience
- expiration
- Application derives local identity from verified claims.
The application should never trust unauthenticated identity headers.
⸻
Add “Do Not Do This” Section
Include examples of insecure approaches:
Bad
Trust X-Forwarded-User because the proxy sets it.
Bad
Trust requests because they originate from an internal network.
Bad
Trust user identity because TLS terminated successfully.
Bad
Allow clients to directly supply identity headers.
⸻
Add “Minimal Application Contract” Section
Applications should:
- expect an identity assertion header
- validate assertions
- reject invalid assertions
- reject expired assertions
- reject missing assertions
- map verified claims into local user identity
- avoid logging assertions or secrets
Applications should not care:
- which proxy authenticated the user
- which IdP authenticated the user
- which authentication flow occurred
Applications should only care that identity is cryptographically verifiable.
⸻
Examples
Node.js Example
Add Express middleware demonstrating:
Environment variables:
TRUSTED_PROXY_ASSERTION_HEADER
TRUSTED_PROXY_JWKS_URL
TRUSTED_PROXY_ISSUER
TRUSTED_PROXY_AUDIENCE
Implementation should use:
jose
and expose:
req.user
after validation.
⸻
Python Example
Add FastAPI middleware demonstrating:
Environment variables:
TRUSTED_PROXY_ASSERTION_HEADER
TRUSTED_PROXY_JWKS_URL
TRUSTED_PROXY_ISSUER
TRUSTED_PROXY_AUDIENCE
Implementation should use:
PyJWT
and expose:
request.state.user
or equivalent.
⸻
Reverse Proxy Example
Add a conceptual NGINX example showing:
- auth_request
- external authorization
- forwarding a signed assertion
The example should explicitly state:
NGINX is forwarding an assertion generated or returned by the authorization service. NGINX itself is not acting as the identity issuer.
⸻
New Section: Why This Pattern Exists
Document that the application should not need to know:
- which proxy authenticated the user
- which authentication provider was used
- how login occurred
The application should only need to know:
A trusted upstream component authenticated the user and provided a cryptographically verifiable identity assertion.
This creates a clean separation between:
- Authentication Infrastructure
- Application Business Logic
⸻
New Section: Ecosystem Gap
Document that there is currently no widely adopted middleware abstraction for trusted proxy identity.
Most teams repeatedly implement:
- JWT validation
- claim extraction
- issuer validation
- audience validation
- middleware integration
even though the pattern is identical across:
- Cloudflare Access
- Pomerium
- OAuth2 Proxy
- Envoy ext_authz
- Traefik ForwardAuth
- NGINX auth_request
- custom authentication gateways
Cloudflare may be referenced as a familiar example but must not be presented as the preferred or recommended solution.
⸻
New Section: Future Middleware Opportunity
Introduce a future open-source middleware project.
Potential package names:
Node.js
@mieweb/trusted-proxy-auth
Python
trusted-proxy-auth
Goals:
Configure:
- assertion header
- issuer
- audience
- JWKS endpoint
Receive:
- verified identity
- framework-native middleware
- consistent claim mapping
- secure defaults
The middleware should remain completely vendor-neutral.
It should work with:
- Cloudflare Access
- Pomerium
- OAuth2 Proxy
- Envoy
- NGINX auth_request
- custom gateways
- future identity-aware proxy implementations
⸻
New Section: Trust Onboarding
Document a proposed onboarding model for future middleware.
Goal:
Provide a one-click administrator experience while preserving cryptographic verification.
Recommended flow:
Administrator
↓
Click "Trust Proxy"
↓
Application validates proxy metadata
↓
Application stores trusted configuration
↓
Runtime continues validating assertions
The onboarding step may:
- verify JWKS availability
- verify issuer
- verify audience
- validate a challenge assertion
- store trusted metadata
The onboarding step should NOT:
Trust the proxy forever after a single successful request.
Instead:
Single-click enrollment.
Continuous verification.
The application should continue validating:
- signatures
- issuer
- audience
- expiration
- key rotation
for every request.
⸻
Design Principles
Include the following principles prominently.
Trust Cryptographic Assertions, Not Infrastructure Brands
Applications should validate identity assertions directly rather than trusting:
- vendor names
- infrastructure products
- network location
- hosting providers
⸻
Authentication Infrastructure Should Be Replaceable
Applications should be portable between:
- Cloudflare Access
- Pomerium
- OAuth2 Proxy
- Authentik
- Keycloak
- Entra
- custom enterprise gateways
without changing application authentication code.
⸻
Identity Is a Contract
Applications should depend on:
Verified Identity Claims
not:
Authentication Vendor
⸻
Acceptance Criteria
- Documentation becomes vendor-neutral.
- Cloudflare appears only as an example.
- Trusted Proxy Identity architecture is documented.
- Identity-Aware Proxy concepts are introduced.
- Security anti-patterns are documented.
- Node.js example is added.
- Python example is added.
- NGINX example is added.
- Ecosystem gap is documented.
- Future middleware opportunity is documented.
- Trust onboarding architecture is documented.
- One-click enrollment + continuous verification model is documented.
- Cryptographic trust is emphasized over vendor trust.
- Documentation establishes a foundation for future trusted-proxy-auth libraries.
Summary
Refactor external-domains.md to document a vendor-neutral Trusted Proxy Identity architecture and establish the foundation for a future cross-platform middleware ecosystem.
The documentation should teach how applications securely consume identity from reverse proxies, ingress controllers, API gateways, and identity-aware proxies without coupling applications to a specific vendor or authentication platform.
This work should also introduce a proposed middleware abstraction that could eventually become:
The goal is to define a portable authentication contract between infrastructure and applications.
⸻
Problem
Modern applications are frequently deployed behind:
Examples include:
All of these products ultimately solve the same problem:
User
↓
Authentication Layer
↓
Application
However, applications currently lack a common, vendor-neutral way to consume verified identity.
Most implementations today fall into one of two categories:
As a result, developers repeatedly implement:
This duplication creates:
⸻
Documentation Goals
Introduce Trusted Proxy Identity
Add documentation describing:
Describe the recommended request flow:
User
↓
Identity-Aware Proxy
↓
Signed Identity Assertion
↓
Application
The application should consume identity, not perform primary authentication.
⸻
Security Model
Add explicit guidance that applications SHOULD NOT trust:
unless they are validated through an established trust boundary.
Document recommended trust mechanisms:
⸻
Preferred MVP Architecture
Document the preferred architecture:
The application should never trust unauthenticated identity headers.
⸻
Add “Do Not Do This” Section
Include examples of insecure approaches:
Bad
Trust X-Forwarded-User because the proxy sets it.
Bad
Trust requests because they originate from an internal network.
Bad
Trust user identity because TLS terminated successfully.
Bad
Allow clients to directly supply identity headers.
⸻
Add “Minimal Application Contract” Section
Applications should:
Applications should not care:
Applications should only care that identity is cryptographically verifiable.
⸻
Examples
Node.js Example
Add Express middleware demonstrating:
Environment variables:
TRUSTED_PROXY_ASSERTION_HEADER
TRUSTED_PROXY_JWKS_URL
TRUSTED_PROXY_ISSUER
TRUSTED_PROXY_AUDIENCE
Implementation should use:
jose
and expose:
req.user
after validation.
⸻
Python Example
Add FastAPI middleware demonstrating:
Environment variables:
TRUSTED_PROXY_ASSERTION_HEADER
TRUSTED_PROXY_JWKS_URL
TRUSTED_PROXY_ISSUER
TRUSTED_PROXY_AUDIENCE
Implementation should use:
PyJWT
and expose:
request.state.user
or equivalent.
⸻
Reverse Proxy Example
Add a conceptual NGINX example showing:
The example should explicitly state:
NGINX is forwarding an assertion generated or returned by the authorization service. NGINX itself is not acting as the identity issuer.
⸻
New Section: Why This Pattern Exists
Document that the application should not need to know:
The application should only need to know:
A trusted upstream component authenticated the user and provided a cryptographically verifiable identity assertion.
This creates a clean separation between:
⸻
New Section: Ecosystem Gap
Document that there is currently no widely adopted middleware abstraction for trusted proxy identity.
Most teams repeatedly implement:
even though the pattern is identical across:
Cloudflare may be referenced as a familiar example but must not be presented as the preferred or recommended solution.
⸻
New Section: Future Middleware Opportunity
Introduce a future open-source middleware project.
Potential package names:
Node.js
@mieweb/trusted-proxy-auth
Python
trusted-proxy-auth
Goals:
Configure:
Receive:
The middleware should remain completely vendor-neutral.
It should work with:
⸻
New Section: Trust Onboarding
Document a proposed onboarding model for future middleware.
Goal:
Provide a one-click administrator experience while preserving cryptographic verification.
Recommended flow:
Administrator
↓
Click "Trust Proxy"
↓
Application validates proxy metadata
↓
Application stores trusted configuration
↓
Runtime continues validating assertions
The onboarding step may:
The onboarding step should NOT:
Trust the proxy forever after a single successful request.
Instead:
Single-click enrollment.
Continuous verification.
The application should continue validating:
for every request.
⸻
Design Principles
Include the following principles prominently.
Trust Cryptographic Assertions, Not Infrastructure Brands
Applications should validate identity assertions directly rather than trusting:
⸻
Authentication Infrastructure Should Be Replaceable
Applications should be portable between:
without changing application authentication code.
⸻
Identity Is a Contract
Applications should depend on:
Verified Identity Claims
not:
Authentication Vendor
⸻
Acceptance Criteria