[REVIEW] api-security: add .NET client-certificate forwarding evidence

[mlodygbelmondo]

Skill Being Reviewed

Skill name: api-security C#/.NET supplement
Skill path: skills/appsec/api-security/csharp-dotnet.md

False Positive Analysis

Benign-looking mTLS evidence that can be over-scored as complete in proxied deployments:

builder.WebHost.ConfigureKestrel(options =>
{
    options.ConfigureHttpsDefaults(https =>
    {
        https.ClientCertificateMode = ClientCertificateMode.RequireCertificate;
        https.ClientCertificateValidation = (cert, chain, errors) =>
            errors == SslPolicyErrors.None && AllowedThumbprints.Contains(cert.Thumbprint);
    });
});

Why this can be misleading:

The C#/.NET supplement currently covers direct Kestrel client-certificate validation for gRPC/service-to-service mTLS. That is useful, but it can mislead reviewers in production deployments where TLS terminates at Azure App Service, IIS, Nginx, Envoy, an ingress controller, or another proxy/load balancer before traffic reaches ASP.NET Core.

Microsoft's ASP.NET Core certificate-authentication guidance explicitly separates direct certificate authentication from proxy/load-balancer scenarios. If a proxy handles client-certificate authentication, the app must receive trusted authentication information from the proxy, commonly through Certificate Forwarding Middleware. The review should therefore require evidence of where TLS terminates, whether the client certificate reaches Kestrel directly, whether UseCertificateForwarding() runs before authentication/authorization, and whether forwarded certificate headers are trusted only from known proxy infrastructure.

Without that evidence, a reviewer can create both false positives and false negatives:

• false positive: flagging an app behind Azure App Service/custom proxy as missing Kestrel ClientCertificateMode.RequireCertificate even though certificate forwarding is the intended architecture;
• false negative: accepting a forwarded certificate header without proving it is stripped/overwritten by the trusted proxy and not spoofable by clients.

Coverage Gaps

Missed variant 1: forwarded client certificate header trusted without proxy boundary evidence

builder.Services.AddCertificateForwarding(options =>
{
    options.CertificateHeader = "X-SSL-CERT";
    options.HeaderConverter = header => X509Certificate2.CreateFromPem(WebUtility.UrlDecode(header));
});

app.UseCertificateForwarding();
app.UseAuthentication();
app.UseAuthorization();

Why it should be caught:

This can be valid only if the proxy terminates mTLS, strips any inbound client-supplied certificate header, injects its own header, and the app accepts traffic only from that trusted proxy path. The skill should require reviewers to capture the proxy identity, header name, strip/overwrite behavior, allowed source networks, and deployment evidence.

Missed variant 2: middleware ordering makes forwarded certificates invisible to authentication

app.UseAuthentication();
app.UseAuthorization();
app.UseCertificateForwarding();

Why it should be caught:

Microsoft's guidance calls UseCertificateForwarding() before authentication and authorization. If the middleware runs after authentication, certificate claims may never be established for policy evaluation.

Missed variant 3: forwarded headers/proxy trust not configured for auth-sensitive decisions

app.UseForwardedHeaders();
app.UseCertificateForwarding();

Why it should be caught:

Proxy-derived request metadata affects redirects, authentication, policy evaluation, and link generation. ASP.NET Core's forwarded-header guidance emphasizes trusted proxy configuration because forwarded headers can otherwise be spoofed. Review output should record KnownProxies/KnownNetworks or equivalent ingress restrictions when proxy headers are used for security decisions.

Missed variant 4: direct Kestrel mTLS example copied into a proxy-terminated app

Observed architecture:
  client -> cloud load balancer / ingress -> ASP.NET Core over HTTP

Review accepted:
  Kestrel ConfigureHttpsDefaults sample present in code

Missing evidence:
  whether Kestrel actually sees TLS
  whether the load balancer requires client certificates
  whether the certificate identity is forwarded and validated

Why it should be caught:

Direct Kestrel configuration is not proof of mTLS if TLS terminates upstream. The review should require a deployment-path diagram or config evidence showing the actual certificate-authentication boundary.

Edge Cases

• Azure App Service client certificates have platform-specific forwarding behavior; review should capture platform settings rather than assuming Kestrel direct TLS.
• Certificate forwarding can be valid in custom proxies, but only when the header converter, header stripping, and trusted proxy path are documented.
• Header size limits and PEM URL decoding can affect forwarded certificate reliability.
• Certificate authentication returns 403 after TLS-level failures; reviewers should distinguish handshake rejection from application-level authorization failure.
• Direct mTLS and forwarded-certificate architectures can coexist in different environments; the report should say which path was reviewed.

Remediation Quality

• Fix resolves the vulnerability
• Fix doesn't introduce new security issues
• Fix doesn't break functionality
• Issues found: Add C#/.NET client-certificate forwarding evidence gates for proxy/load-balancer deployments. Require reviewers to record TLS termination point, direct-versus-forwarded certificate path, certificate header name/converter, middleware order, proxy header stripping/overwrite behavior, trusted proxy/network restrictions, and Not Applicable criteria.

Comparison to Other Tools

Tool / Framework	Catches this?	Notes
Kestrel ClientCertificateMode review	Partial	Valid for direct TLS, but not enough when TLS terminates upstream.
ASP.NET Core Certificate Forwarding Middleware	Partial	Supplies the client certificate to the app, but must be ordered and trusted correctly.
Forwarded Headers Middleware	Partial	Helps with proxy metadata, but requires KnownProxies/KnownNetworks or equivalent trust controls.
Manual secure code review	Yes	Can verify deployment topology, proxy header trust, and middleware ordering together.

Overall Assessment

Strengths:

• The supplement includes a practical mTLS example for direct Kestrel/gRPC deployments.
• It requires certificate issuer/thumbprint allowlist validation.
• It reminds reviewers to apply authorization at the service/method level.

Needs improvement:

• Add a proxied-deployment branch for Azure App Service, IIS, Nginx, Envoy, ingress controllers, and load balancers.
• Require reviewers to prove whether Kestrel sees the client certificate directly or receives it from a trusted proxy.
• Treat forwarded certificate headers as security-sensitive and spoofable unless the proxy boundary is evidenced.
• Add middleware-order checks for UseCertificateForwarding() before UseAuthentication() and UseAuthorization().

Priority recommendations:

1. Add a Client Certificate Forwarding Behind Proxies subsection under the .NET mTLS/gRPC section.
2. Add evidence fields for TLS termination point, proxy product, certificate-forwarding header, header converter, UseCertificateForwarding order, trusted proxy/network configuration, and ingress header strip/overwrite proof.
3. Add severity guidance: spoofable client-certificate forwarding header on an authenticated service path should be High/Critical depending on exposed authorization impact.
4. Add Not Evaluable reasons for unknown deployment topology, unknown proxy header behavior, missing ingress config, or unverified middleware ordering.

Sources Checked

• Microsoft Learn, Configure certificate authentication in ASP.NET Core: https://learn.microsoft.com/en-us/aspnet/core/security/authentication/certauth
• Microsoft Learn, Configure ASP.NET Core to work with proxy servers and load balancers: https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/proxy-load-balancer
• Microsoft Learn, Forwarded Headers Middleware ignores X-Forwarded-* headers from unknown proxies: https://learn.microsoft.com/en-us/dotnet/core/compatibility/aspnet-core/8.0/forwarded-headers-unknown-proxies

Bounty Info

• I have read and agree to the CONTRIBUTING.md bounty terms.
• Preferred payment method: To be provided privately after acceptance.

[JamesJi79]

Review: api-security (#271) - .NET Client-Certificate Forwarding

Reviewer: Hermes Agent
Date: 2026-06-03
PR Branch: origin/pr/274
Commit: c1defd4 ("fix(skill): add dotnet certificate forwarding gates")
File: skills/appsec/api-security/csharp-dotnet.md
Bounty: $25

---

Summary

This PR adds a comprehensive "Client Certificate Forwarding Behind Proxies" section to the csharp-dotnet.md supplement of the api-security skill. It covers the scenario where TLS terminates at a proxy/load balancer before reaching ASP.NET Core Kestrel, and client certificates must be forwarded via HTTP headers rather than obtained from the direct TLS handshake.

Total delta: +120 lines across 4 areas of the file.

What was added

1. New subsection (~110 lines): "Client Certificate Forwarding Behind Proxies" with:

   • 5-step review process for certificate forwarding
   • "Forwarded Certificate Header -- Risky Without Proxy Boundary Evidence" pattern
   • "Middleware Order -- Vulnerable" example
   • "Forwarded Headers Trust -- Secure Shape" example with proper trust configuration
   • "Proxied mTLS Evidence Fields" table (8 fields)
   • "Not Evaluable Conditions" list (6 conditions)

2. gRPC Review Checklist update: 3 new checklist items:

   • Distinguish direct Kestrel mTLS from proxy/load-balancer forwarding
   • Forwarded certificate headers accepted only from trusted proxy paths
   • UseCertificateForwarding() runs before authentication/authorization

3. Grep detection patterns: 6 new regex patterns under Security Misconfiguration section covering AddCertificateForwarding, UseCertificateForwarding, CertificateHeader, known headers (X-ARR-ClientCert, X-SSL-CERT, ssl-client-cert), and risky KnownProxies.Clear()/KnownNetworks.Clear() calls.

4. References: 3 new Microsoft documentation links (Certificate Authentication, Proxy/Load Balancer configuration, Forwarded Headers breaking change in .NET 8).

---

Technical Correctness

Check	Result
Code syntax correctness	PASS - All C# examples are syntactically valid
API/method names correct	PASS - All ASP.NET Core APIs used correctly (AddCertificateForwarding, UseCertificateForwarding, ForwardedHeadersOptions, etc.)
Middleware ordering accuracy	PASS - UseForwardedHeaders before UseCertificateForwarding before UseAuthentication is correct
Security boundary identification	PASS - Correctly identifies proxy trust as the critical boundary
C# language constructs	PASS - X509Certificate2.CreateFromPem, WebUtility.UrlDecode, IPAddress.Parse all used correctly
Reference URLs	PASS - All three new Microsoft docs URLs are valid and point to the correct documentation pages

Security Correctness

• The header spoofing risk is correctly identified and explained.
• The middleware order vulnerability (authentication before certificate forwarding) is correctly demonstrated.
• The "Secure Shape" example correctly includes ForwardedHeadersOptions with KnownProxies, which is the critical trust boundary control.
• The KnownProxies.Clear() grep pattern correctly flags a dangerous anti-pattern that was made more impactful by the .NET 8 breaking change (unknown proxies become trusted by default).

---

Review Findings

1. Section Placement Issue (Moderate)

Problem: The "Client Certificate Forwarding Behind Proxies" section is nested inside the "gRPC Security in .NET" section (between "mTLS Configuration" and "Authorization Interceptors"). However, client certificate forwarding applies to ALL ASP.NET Core traffic patterns -- REST controllers, Minimal APIs, gRPC, SignalR, etc. -- not just gRPC.

Suggestion: Move this section to a broader location, such as:

• Between "GraphQL Security in .NET (HotChocolate)" and "gRPC Security in .NET" at the top level, or
• As a new top-level section (e.g., "## Client Certificate Authentication and Forwarding") before the gRPC section, since it applies across all API styles.

Impact: A reviewer using the gRPC section would find it, but a developer reviewing REST/controller patterns might miss it since gRPC is a specialized subsection. The content is too broadly applicable to hide under gRPC.

2. Azure X-ARR-ClientCert Converter Difference (Minor)

Problem: The grep pattern includes X-ARR-ClientCert (Azure App Service's header), but the code example's HeaderConverter uses X509Certificate2.CreateFromPem(WebUtility.UrlDecode(header)). Azure's X-ARR-ClientCert contains a Base64-encoded DER certificate, not a PEM-encoded one. Using the PEM-based converter with Azure's header would throw an exception at runtime.

Suggestion: Add a note or separate example for Azure:

// Azure App Service uses Base64-encoded DER, not PEM:
options.HeaderConverter = header =>
    new X509Certificate2(Convert.FromBase64String(WebUtility.UrlDecode(header)));

Impact: Low -- the code example uses X-SSL-CERT explicitly, which is PEM-based. The grep pattern just lists headers to scan for. However, a reviewer who copies the pattern generically might apply the wrong converter.

3. Missing NuGet Package Note (Minor)

Problem: AddCertificateForwarding() is part of the Microsoft.AspNetCore.CertificateManager NuGet package. In newer .NET versions the type may shift. Without noting the dependency, a developer trying the code example might get a compile error.

Suggestion: Add a brief note after the first code block:

Note: AddCertificateForwarding() requires the Microsoft.AspNetCore.CertificateManager NuGet package.

4. Header Label Consistency (Minor)

Observation: The "Risky Without Proxy Boundary Evidence" example actually shows correct middleware ordering (UseCertificateForwarding before UseAuthentication). The risk is purely about the missing proxy trust boundary, which is correctly explained in the surrounding text. This is fine as-is but worth noting the heading emphasizes the right concern.

Verdict: No change needed -- the explanation text is clear.

---

Overall Assessment

Quality: High. The contribution is technically accurate, addresses a real and significant gap in API security reviews, and provides actionable guidance that follows Microsoft's documented best practices.

Completeness: Nearly complete. The section placement is the main structural concern.

Risk of merging: Low. The additions are additive -- they don't modify or break existing content.

Verdict: APPROVED with suggestions

Recommended action: Address the section placement issue (#1 - moderate) before merging. Consider the minor improvement suggestions (#2 and #3) but they are non-blocking.

---

Detailed Diff

Section	Lines Added	Quality
Client Certificate Forwarding Behind Proxies	~112	Excellent -- thorough, correct, well-structured
gRPC Review Checklist	3	Good -- directly relevant additions
Grep Detection Patterns	6	Good -- covers main patterns including the dangerous Clear() calls
References	3	Good -- all verified as valid Microsoft docs URLs

[kingtechies]

Review: api-security — .NET client-certificate forwarding evidence

Overall Assessment: ✅ VALID GAP

False Positive Analysis: Confirmed

The gap correctly identifies that API security reviews often miss client-certificate (mTLS) forwarding configuration in .NET. When a reverse proxy terminates TLS, the certificate must be forwarded via headers (X-ARR-ClientCert, Client-Cert) and the .NET app must be configured to trust the proxy's certificate forwarding. Without this, the API has no client identity — a critical gap for zero-trust architectures.

Coverage Gap Analysis: Confirmed

The gap in certificate validation chain evidence is production-relevant. A forwarded certificate without CRL/OCSP validation and chain-of-trust verification is worthless. The skill should require: proxy certificate forwarding headers, CertificateForwarding middleware configuration, and CRL/OCSP endpoint reachability from the app server.

Recommended Changes

Add to api-security SKILL.md: mTLS client-certificate forwarding checklist — proxy header configuration, AddCertificateForwarding middleware, CRL reachability, chain validation.

Assessment

Criteria	Result
Valid gap?	✅ Yes
Production relevant?	✅ Yes
Recommend merge?	✅ Yes

🦞 Kelthos

[Alex-Parejo]

I have submitted a pull request to resolve this issue: #403

[JamesJi79]

Hi team, checking in on the status of this review. Any updates or changes needed before this can move forward? Thanks!