YARP Basics

Back to Index

Reverse Proxy in .NET

Microsoft created YARP (Yet Another Reverse Proxy).

YARP is built on ASP.NET Core.

Benefits:

High performance
Native .NET
Easy configuration
Cloud friendly

What is YARP?

YARP (Yet Another Reverse Proxy) is an open-source reverse proxy framework for .NET developed by Microsoft. It allows you to build a high-performance proxy server that receives client requests and forwards them to backend applications or services.

Instead of users accessing the backend applications directly, they connect to YARP, which decides where to send each request.

Why Use YARP?

YARP can help with:

Load balancing across multiple servers
Centralized authentication and authorization
SSL/TLS termination
URL rewriting
Routing requests to different applications
API Gateway scenarios
Microservices architectures

Simple Example

Suppose you have:

Frontend API running on http://localhost:5001
Admin API running on http://localhost:5002

Using YARP, you can expose a single endpoint:

[http://localhost:8080/api/*](http://localhost:8080/api/*)

[http://localhost:8080/admin/*](http://localhost:8080/admin/*)

YARP configuration:

{
  "ReverseProxy": {
    "Routes": {
      "apiRoute": {
        "ClusterId": "apiCluster",
        "Match": {
          "Path": "/api/{**catch-all}"
        }
      }
    },

    "Clusters": {
      "apiCluster": {
        "Destinations": {
          "destination1": {
            "Address": "[http://localhost:5001/](http://localhost:5001/)"
          }
        }
      }
    }
  }
}

ASP.NET Core Setup

Install package:

dotnet add package Yarp.ReverseProxy

Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services
       .AddReverseProxy()
       .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();

app.MapReverseProxy();

app.Run();

Real-World Example

Imagine you have:

Customer Portal → http://localhost:7001
Employee Portal → http://localhost:7002

Users access:

[https://company.com/customer](https://company.com/customer)

[https://company.com/employee](https://company.com/employee)

YARP receives the requests and forwards them to the correct internal application. The users never see the internal server addresses.

Why Microsoft Created YARP

Microsoft created YARP to provide:

A modern reverse proxy solution built specifically for ASP.NET Core
High performance using .NET's networking stack
Easy customization using C#
Better integration with cloud-native and microservice applications

Implementing Reverse Proxy with YARP

Step 1: Create Project

dotnet new web

Install package:

dotnet add package Yarp.ReverseProxy

Step 2: appsettings.json

{
  "ReverseProxy": {
    "Routes": {
      "route1": {
        "ClusterId": "api-cluster",
        "Match": {
          "Path": "{**catch-all}"
        }
      }
    },
    "Clusters": {
      "api-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "https://localhost:7000/"
          }
        }
      }
    }
  }
}

Step 3: Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddReverseProxy()
    .LoadFromConfig(
        builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();

app.MapReverseProxy();

app.Run();

Step 4: Run

Proxy:

https://localhost:5000

Backend:

https://localhost:7000

Request:

https://localhost:5000/api/users

YARP forwards:

https://localhost:7000/api/users

Example: API Gateway Pattern

Architecture:

Internet
    |
    v
YARP Gateway
    |
    +--> User API
    |
    +--> Product API
    |
    +--> Order API

Configuration:

{
  "ReverseProxy": {
    "Routes": {
      "users": {
        "ClusterId": "usersCluster",
        "Match": {
          "Path": "/users/{**catch-all}"
        }
      },
      "products": {
        "ClusterId": "productCluster",
        "Match": {
          "Path": "/products/{**catch-all}"
        }
      }
    },
    "Clusters": {
      "usersCluster": {
        "Destinations": {
          "d1": {
            "Address": "https://localhost:7001/"
          }
        }
      },
      "productCluster": {
        "Destinations": {
          "d1": {
            "Address": "https://localhost:7002/"
          }
        }
      }
    }
  }
}

Production Example

A typical enterprise setup:

Each layer has a responsibility:

Component	Responsibility
Front Door	Global routing
WAF	Security
YARP	Service routing
Services	Business logic

Best Practices

1. Enable HTTPS Everywhere

Good:

User -> HTTPS -> Proxy -> HTTPS -> App

Avoid:

User -> HTTPS -> Proxy -> HTTP -> App

Especially across networks.

2. Configure Forwarded Headers

Without this, ASP.NET may see the proxy IP instead of the real client.

builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders =
        ForwardedHeaders.XForwardedFor |
        ForwardedHeaders.XForwardedProto;
});

app.UseForwardedHeaders();

3. Add Health Checks

builder.Services.AddHealthChecks();

Use proxy health probes.

4. Rate Limiting

Protect against abuse.

builder.Services.AddRateLimiter(...);

5. Logging

Log:

Request ID
Correlation ID
User ID
Source IP

Useful for distributed systems.

6. Use Load Balancing

Avoid single backend:

Proxy
 |
 +--App1
 +--App2
 +--App3

7. Use Service Discovery

For Kubernetes or cloud-native apps:

Proxy -> Service Name -> Pods

instead of hardcoded IPs.

Common Mistakes

Mistake 1: Infinite Loop

Bad:

Proxy -> Proxy -> Proxy -> Proxy

Verify backend URLs carefully.

Mistake 2: Large Request Bodies

Uploading:

2 GB file

may fail due to proxy limits.

Configure:

Request size
Timeouts
Buffer sizes

Mistake 3: Ignoring X-Forwarded Headers

Then:

HttpContext.Connection.RemoteIpAddress

returns proxy IP instead of client IP.

Mistake 4: Session-Based Applications

Bad architecture:

Proxy
 |
 +-- App1
 +-- App2

with in-memory sessions.

Use:

Redis
Distributed Cache
Database-backed session storage

Mistake 5: Single Point of Failure