Skip to content

Commit f42f4f7

Browse files
Rick-AndersonRick-Anderson
authored
Yarp/stage to main (#34680)
* YARP migration /2 (#34657) * YARP migration /2 * YARP migration /2 * YARP migration /2 * YARP migration /2 * YARP migration /2 * YARP migration /2 * YARP migration /2 * YARP migration /2 * YARP migration /2 * YARP migration /2 * YARP migration /2 * YARP migration /2 * YARP migration /2 * YARP migration /2 * YARP migration /2 * Yarb pass 2 (#34667) * Yarb pass 2 * Yarb pass 2 * fix * fix * fix * fix * YARP owner (#34675) * YARP owner * YARP owner * Yarp/Stage to main /2 * Yarp/Stage to main /2
1 parent b45aab3 commit f42f4f7

33 files changed

+5406
-1
lines changed

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

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
uid: fundamentals/servers/yarp/ab-testing
3+
title: A/B Testing and Rolling Upgrades
4+
description: A/B Testing and Rolling Upgrades
5+
author: samsp-msft
6+
ms.author: samsp
7+
ms.date: 2/6/2025
8+
ms.topic: article
9+
content_well_notification: AI-contribution
10+
ai-usage: ai-assisted
11+
---
12+
13+
# YARP A/B Testing and Rolling Upgrades
14+
15+
## Introduction
16+
17+
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.
18+
19+
## Example
20+
21+
```
22+
app.MapReverseProxy(proxyPipeline =>
23+
{
24+
// Custom cluster selection
25+
proxyPipeline.Use((context, next) =>
26+
{
27+
var lookup = context.RequestServices.GetRequiredService<IProxyStateLookup>();
28+
if (lookup.TryGetCluster(ChooseCluster(context), out var cluster))
29+
{
30+
context.ReassignProxyRequest(cluster);
31+
}
32+
33+
return next();
34+
});
35+
proxyPipeline.UseSessionAffinity();
36+
proxyPipeline.UseLoadBalancing();
37+
});
38+
39+
string ChooseCluster(HttpContext context)
40+
{
41+
// Decide which cluster to use. This could be random, weighted, based on headers, etc.
42+
return Random.Shared.Next(2) == 1 ? "cluster1" : "cluster2";
43+
}
44+
```
45+
46+
## Usage
47+
48+
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.
49+
50+
`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`.
51+
52+
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.
53+
54+
## Session affinity
55+
56+
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.
57+

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

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
uid: fundamentals/servers/yarp/authn-authz
3+
title: Authentication and Authorization
4+
description: Authentication and Authorization
5+
author: samsp-msft
6+
ms.author: samsp
7+
ms.date: 2/6/2025
8+
ms.topic: article
9+
content_well_notification: AI-contribution
10+
ai-usage: ai-assisted
11+
---
12+
13+
# YARP Authentication and Authorization
14+
15+
## Introduction
16+
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.
17+
18+
## Defaults
19+
20+
No authentication or authorization is performed on requests unless enabled in the route or application configuration.
21+
22+
## Configuration
23+
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.
24+
25+
Example:
26+
```JSON
27+
{
28+
"ReverseProxy": {
29+
"Routes": {
30+
"route1" : {
31+
"ClusterId": "cluster1",
32+
"AuthorizationPolicy": "customPolicy",
33+
"Match": {
34+
"Hosts": [ "localhost" ]
35+
}
36+
}
37+
},
38+
"Clusters": {
39+
"cluster1": {
40+
"Destinations": {
41+
"cluster1/destination1": {
42+
"Address": "https://localhost:10001/"
43+
}
44+
}
45+
}
46+
}
47+
}
48+
}
49+
```
50+
51+
[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.
52+
53+
Authorization policies can be configured in the application as follows:
54+
```
55+
services.AddAuthorization(options =>
56+
{
57+
options.AddPolicy("customPolicy", policy =>
58+
policy.RequireAuthenticatedUser());
59+
});
60+
```
61+
62+
In Program.cs add the Authorization and Authentication middleware.
63+
64+
```
65+
app.UseAuthentication();
66+
app.UseAuthorization();
67+
68+
app.MapReverseProxy();
69+
```
70+
71+
See the [Authentication](/aspnet/core/security/authentication/) docs for setting up your preferred kind of authentication.
72+
73+
### Special values:
74+
75+
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.
76+
77+
#### DefaultPolicy
78+
79+
Specifying the value `default` in a route's authorization parameter means that route will use the policy defined in [AuthorizationOptions.DefaultPolicy](/dotnet/api/microsoft.aspnetcore.authorization.authorizationoptions.defaultpolicy?#Microsoft_AspNetCore_Authorization_AuthorizationOptions_DefaultPolicy). That policy is pre-configured to require authenticated users.
80+
81+
#### Anonymous
82+
83+
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.
84+
85+
#### FallbackPolicy
86+
87+
[AuthorizationOptions.FallbackPolicy](/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.
88+
89+
## Flowing Credentials
90+
91+
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.
92+
93+
### Cookie, bearer, API keys
94+
95+
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.
96+
97+
### OAuth2, OpenIdConnect, WsFederation
98+
99+
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.
100+
101+
### Windows, Negotiate, NTLM, Kerberos
102+
103+
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.
104+
105+
### Client Certificates
106+
107+
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.
108+
109+
### Swapping authentication types
110+
111+
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.
112+
113+
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.

0 commit comments

Comments
 (0)