YARP migration /2

aspnetcore/fundamentals/servers/yarp/ab-testing.md

@@ -0,0 +1,58 @@
+---
+uid: fundamentals/servers/yarp/ab-testing
+title: A/B Testing and Rolling Upgrades
+description: A/B Testing and Rolling Upgrades
+author: rick-anderson
+ms.author: riande
+ms.date: 02/06/2025
+ms.topic: article
+content_well_notification: AI-contribution
+ms.prod: aspnet-core
+ai-usage: ai-assisted
+---
+
+# A/B Testing and Rolling Upgrades
+
+## Introduction
+
+A/B testing and rolling upgrades require procedures for dynamically assigning incoming traffic to evaluate changes in the destination application. YARP does not have a built-in model for this, but it does expose some infrastructure useful for building such a system. See [issue #126](https://github.com/microsoft/reverse-proxy/issues/126) for additional details about this scenario.
+
+## Example
+
+```
+app.MapReverseProxy(proxyPipeline =>
+{
+    // Custom cluster selection
+    proxyPipeline.Use((context, next) =>
+    {
+        var lookup = context.RequestServices.GetRequiredService<IProxyStateLookup>();
+        if (lookup.TryGetCluster(ChooseCluster(context), out var cluster))
+        {
+            context.ReassignProxyRequest(cluster);
+        }
+
+        return next();
+    });
+    proxyPipeline.UseSessionAffinity();
+    proxyPipeline.UseLoadBalancing();
+});
+
+string ChooseCluster(HttpContext context)
+{
+    // Decide which cluster to use. This could be random, weighted, based on headers, etc.
+    return Random.Shared.Next(2) == 1 ? "cluster1" : "cluster2";
+}
+```
+
+## Usage
+
+This scenario makes use of two APIs, [IProxyStateLookup](xref:Yarp.ReverseProxy.IProxyStateLookup) and [ReassignProxyRequest](xref:Microsoft.AspNetCore.Http.HttpContextFeaturesExtensions.ReassignProxyRequest(Microsoft.AspNetCore.Http.HttpContext,Yarp.ReverseProxy.Model.ClusterState)), called from a custom proxy middleware as shown in the sample above.
+
+`IProxyStateLookup` is a service available in the Dependency Injection container that can be used to look up or enumerate the current routes and clusters. Note this data may change if the configuration changes. An A/B orchestration algorithm can examine the request, decide which cluster to send it to, and then retrieve that cluster from `IProxyStateLookup.TryGetCluster`.
+
+Once the cluster is selected, `ReassignProxyRequest` can be called to assign the request to that cluster. This updates the [IReverseProxyFeature](xref:Yarp.ReverseProxy.Model.IReverseProxyFeature) with the new cluster and destination information needed for the rest of the proxy middleware pipeline to handle the request.
+
+## Session affinity
+
+Note that session affinity functionality is split between middleware, which reads it settings from the current cluster, and transforms, which are part of the original route. Clusters used for A/B testing should use the same session affinity configuration to avoid conflicts.
+

aspnetcore/fundamentals/servers/yarp/authn-authz.md

@@ -0,0 +1,114 @@
+---
+uid: fundamentals/servers/yarp/authn-authz
+title: Authentication and Authorization
+description: Authentication and Authorization
+author: rick-anderson
+ms.author: riande
+ms.date: 02/06/2025
+ms.topic: article
+content_well_notification: AI-contribution
+ms.prod: aspnet-core
+ai-usage: ai-assisted
+---
+
+# Authentication and Authorization
+
+## Introduction
+The reverse proxy can be used to authenticate and authorize requests before they are proxied to the destination servers. This can reduce load on the destination servers, add a layer of protection, and ensure consistent policies are implemented across your applications.
+
+## Defaults
+
+No authentication or authorization is performed on requests unless enabled in the route or application configuration.
+
+## Configuration
+Authorization policies can be specified per route via [RouteConfig.AuthorizationPolicy](xref:Yarp.ReverseProxy.Configuration.RouteConfig) and can be bound from the `Routes` sections of the config file. As with other route properties, this can be modified and reloaded without restarting the proxy. Policy names are case insensitive.
+
+Example:
+```JSON
+{
+  "ReverseProxy": {
+    "Routes": {
+      "route1" : {
+        "ClusterId": "cluster1",
+        "AuthorizationPolicy": "customPolicy",
+        "Match": {
+          "Hosts": [ "localhost" ]
+        }
+      }
+    },
+    "Clusters": {
+      "cluster1": {
+        "Destinations": {
+          "cluster1/destination1": {
+            "Address": "https://localhost:10001/"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+[Authorization policies](/aspnet/core/security/authorization/policies) are an ASP.NET Core concept that the proxy utilizes. The proxy provides the above configuration to specify a policy per route and the rest is handled by existing ASP.NET Core authentication and authorization components.
+
+Authorization policies can be configured in the application as follows:
+```
+services.AddAuthorization(options =>
+{
+    options.AddPolicy("customPolicy", policy =>
+        policy.RequireAuthenticatedUser());
+});
+```
+
+In Program.cs add the Authorization and Authentication middleware.
+
+```
+app.UseAuthentication();
+app.UseAuthorization();
+
+app.MapReverseProxy();
+```
+
+See the [Authentication](/aspnet/core/security/authentication/) docs for setting up your preferred kind of authentication.
+
+### Special values:
+
+In addition to custom policy names, there are two special values that can be specified in a route's authorization parameter: `default` and `anonymous`. ASP.NET Core also has a FallbackPolicy setting that applies to routes that do not specify a policy.
+
+#### DefaultPolicy
+
+Specifying the value `default` in a route's authorization parameter means that route will use the policy defined in [AuthorizationOptions.DefaultPolicy](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.authorization.authorizationoptions.defaultpolicy?#Microsoft_AspNetCore_Authorization_AuthorizationOptions_DefaultPolicy). That policy is pre-configured to require authenticated users.
+
+#### Anonymous
+
+Specifying the value `anonymous` in a route's authorization parameter means that route will not require authorization regardless of any other configuration in the application such as the FallbackPolicy.
+
+#### FallbackPolicy
+
+[AuthorizationOptions.FallbackPolicy](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.authorization.authorizationoptions.fallbackpolicy) is the policy that will be used for any request or route that was not configured with a policy. FallbackPolicy does not have a value by default, any request will be allowed.
+
+## Flowing Credentials
+
+Even after a request has been authorized in the proxy, the destination server may still need to know who the user is (authentication) and what they're allowed to do (authorization). How you flow that information will depend on the type of authentication being used.
+
+### Cookie, bearer, API keys
+
+These authentication types already pass their values in the request headers and these will flow to the destination server by default. That server will still need to verify and interpret those values, causing some double work.
+
+### OAuth2, OpenIdConnect, WsFederation
+
+These protocols are commonly used with remote identity providers. The authentication process can be configured in the proxy application and will result in an authentication cookie. That cookie will flow to the destination server as a normal request header.
+
+### Windows, Negotiate, NTLM, Kerberos
+
+These authentication types are often bound to a specific connection. They are not supported as means of authenticating a user in a destination server behind the YARP proxy (see [#166](https://github.com/microsoft/reverse-proxy/issues/166). They can be used to authenticate an incoming request to the proxy, but that identity information will have to be communicated to the destination server in another form. They can also be used to authenticate the proxy to the destination servers, but only as the proxy's own user, impersonating the client is not supported.
+
+### Client Certificates
+
+Client certificates are a TLS feature and are negotiated as part of a connection. See [these docs](/aspnet/core/security/authentication/certauth) for additional information. The certificate can be forwarded to the destination server as an HTTP header using the [ClientCert](transforms.md#clientcert) transform.
+
+### Swapping authentication types
+
+Authentication types like Windows that don't flow naturally to the destination server will need to be converted in the proxy to an alternate form. For example a JWT bearer token can be created with the user information and set on the proxy request.
+
+These swaps can be performed using [custom request transforms](transforms.md#from-code). Detailed examples can be developed for specific scenarios if there is enough community interest. We need more community feedback on how you want to convert and flow identity information.