This Claude skill streamlines the configuration of YARP (Yet Another Reverse Proxy) for the affolterNET.Web.Bff framework. It simplifies the setup of API proxying, route management, and backend service integration, ensuring secure communication through automated authentication token forwarding and optimized path rewriting.

When should I use yarp-proxy?

yarp-proxy is useful in the following scenarios: • Setting up a Backend-for-Frontend (BFF) architecture to securely proxy requests from client applications to multiple backend microservices. • Automating the attachment of bearer tokens to proxied API requests using AuthTransforms for seamless user session propagation. • Configuring complex routing rules, including path rewriting and prefix removal, to map external URLs to internal service endpoints. • Troubleshooting and resolving common proxy issues such as 502 Bad Gateway errors, routing mismatches, and destination connectivity problems.

name	yarp-proxy
description	Configure YARP reverse proxy for affolterNET.Web.Bff. Use when setting up API proxying, route configuration, or backend service integration.

YARP Reverse Proxy

Configure YARP to proxy requests to backend APIs.

For complete reference, see Library Guide.

Quick Start

appsettings.json

{
  "affolterNET": {
    "ReverseProxy": {
      "Routes": {
        "api-route": {
          "ClusterId": "api-cluster",
          "Match": {
            "Path": "/api/{**catch-all}"
          }
        }
      },
      "Clusters": {
        "api-cluster": {
          "Destinations": {
            "api": {
              "Address": "https://api.example.com"
            }
          }
        }
      }
    }
  }
}

How It Works

BFF receives request to /api/...
YARP matches the route pattern
AuthTransform adds bearer token from user session
Request is forwarded to backend API
Response is returned to client

Configuration Options

Routes

{
  "Routes": {
    "route-name": {
      "ClusterId": "cluster-name",
      "Match": {
        "Path": "/api/{**catch-all}",
        "Methods": ["GET", "POST"]
      },
      "Transforms": []
    }
  }
}

Clusters

{
  "Clusters": {
    "cluster-name": {
      "Destinations": {
        "destination1": {
          "Address": "https://api1.example.com"
        },
        "destination2": {
          "Address": "https://api2.example.com"
        }
      },
      "LoadBalancingPolicy": "RoundRobin"
    }
  }
}

Auth Transform

The BFF automatically adds bearer tokens to proxied requests:

// Automatically extracts access token from user session
var token = await context.GetTokenAsync("access_token");
// Adds Authorization: Bearer {token} header

Multiple Backend APIs

{
  "affolterNET": {
    "ReverseProxy": {
      "Routes": {
        "users-api": {
          "ClusterId": "users",
          "Match": { "Path": "/api/users/{**catch-all}" }
        },
        "orders-api": {
          "ClusterId": "orders",
          "Match": { "Path": "/api/orders/{**catch-all}" }
        }
      },
      "Clusters": {
        "users": {
          "Destinations": {
            "default": { "Address": "https://users-api.example.com" }
          }
        },
        "orders": {
          "Destinations": {
            "default": { "Address": "https://orders-api.example.com" }
          }
        }
      }
    }
  }
}

Path Rewriting

{
  "Routes": {
    "api-route": {
      "ClusterId": "api",
      "Match": { "Path": "/bff/api/{**remainder}" },
      "Transforms": [
        { "PathRemovePrefix": "/bff" }
      ]
    }
  }
}

Troubleshooting

502 Bad Gateway

Verify backend API is running and accessible
Check destination address is correct
Review network connectivity between BFF and API

Token not forwarded

Ensure user is authenticated
Verify access token is in session
Check AuthTransform is registered

Route not matched

Verify path pattern matches incoming request
Check route order (more specific routes first)
Enable YARP logging for debugging

yarp-proxy

When & Why to Use This Skill

Use Cases