Endpoint with AllowAnonymous() returns 401 when API version is unsupported or unspecified

[naegelejd]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

I am using Minimal APIs with Asp.Versioning.Mvc 8.1.0.

I have Authentication and Authorization enabled with default JWT-Bearer Authentication scheme and default Authorization policy (the only requirement is DenyAnonymousAuthorizationRequirement).

As expected, with Authentication/Authorization disabled, I get a 400 Bad Request response when I provide an invalid API version in a client request (or omit the API version altogether).

However, if I enable Authentication/Authorization, and use .AllowAnonymous() to bypass the authorization requirement on an endpoint, I get a 401 Unauthorized response for the same requests.

Is this the expected behavior? Either way, is there a way to work around this so that we can return a 401 response?

Expected Behavior

When I use .AllowAnonymous() on an endpoint, I expect to receive a 401 Bad Request when a client request omits the API version or provides an invalid API version.

Steps To Reproduce

Minimal server to reproduce:

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.Authorization;
using Microsoft.Extensions.Options;
using Asp.Versioning;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication().AddJwtBearer();

builder.Services.AddAuthorization();
builder.Services.AddOptions<AuthorizationOptions>().Configure((authOptions) =>
{
    authOptions.FallbackPolicy = new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build();
});


builder.Services.AddApiVersioning(options =>
{
    options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
});

var app = builder.Build();

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

var api = app.NewVersionedApi();
api.MapGet("/foo", () => "Hello World!").AllowAnonymous().HasApiVersion(1.0);

app.Run();

Demo:

$ curl -i http://localhost:5080/foo?api-version=1.0
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Tue, 22 Apr 2025 20:49:15 GMT
Server: Kestrel
Transfer-Encoding: chunked

$ curl -i http://localhost:5080/foo?api-version=1.1
HTTP/1.1 401 Unauthorized
Content-Length: 0
Date: Tue, 22 Apr 2025 20:49:18 GMT
Server: Kestrel
WWW-Authenticate: Bearer

$ curl -i http://localhost:5080/foo
HTTP/1.1 401 Unauthorized
Content-Length: 0
Date: Tue, 22 Apr 2025 20:49:29 GMT
Server: Kestrel
WWW-Authenticate: Bearer

Exceptions (if any)

No response

.NET Version

9.0.102

Anything else?

No response

[commonsensesoftware]

I might be missing something, but I don't see a mapping for 1.1. My best guess is that endpoint selection is being short-circuited and returning 401 before API versioning has a chance to return 400.

If you add support for 1.1, then I expect it to work the same way as 1.0, which seems to be correct:

var root = api.MapGroup("/foo").HasApiVersion(1.0).HasApiVersion(1.1);

[naegelejd]

@commonsensesoftware

I slightly simplified my example above, removing the group so we can just focus on these lines:

var api = app.NewVersionedApi();
api.MapGet("/foo", () => "Hello World!").AllowAnonymous().HasApiVersion(1.0);

What response should I get when I run curl http://localhost:5080/foo?
I would expect either 200 Ok, or 400 Bad Request because I'm missing the required, valid API version (1.0). But instead, I'm getting a 401 Unauthorized, which is simply incorrect.

If I remove ApiVersioning and run that command, I get a 200 Ok:

app.MapGet("/foo", () => "Hello World!").AllowAnonymous();

Perhaps something is being short-circuited but it would seem to be a bug because it's short-circuiting the .AllowAnonymous(). The documentation for AllowAnonymous says "This will bypass all authorization checks for the endpoint including the default authorization policy and fallback authorization policy".

I'm happy to work around it if you have any insights. Thanks!

[commonsensesoftware]

I dove into this some more and I think this is the expected behavior.

First, you can simplify the setup by having the fallback policy be the same as the default policy. There are equivalent in this case. For example:

builder.Services.AddOptions()
                .Configure( ( AuthorizationOptions options ) => options.FallbackPolicy = options.DefaultPolicy );

You can see how AuthorizationOptions.DefaultPolicy is setup here:

https://github.com/dotnet/aspnetcore/blob/c61ff67f47ce948d10d2e4c00ad48bea17ce7314/src/Security/Authorization/Core/src/AuthorizationOptions.cs#L35

The AuthorizationPolicy is picked up and enforced by the AuthorizationMiddleware:

https://github.com/dotnet/aspnetcore/blob/c61ff67f47ce948d10d2e4c00ad48bea17ce7314/src/Security/Authorization/Policy/src/AuthorizationMiddleware.cs#L93

You see that it is looking for any Endpoint. An Endpoint is the logical destination, but it is not a Response, which means it doesn't have a status code, etc. API Versioning configures the routing system to return UnspecifiedApiVersionEndpoint and UnsupportedApiVersionEndpoint respectively for the scenarios you called out. In these cases, there is an Endpoint, but there is no attached authorization metadata. As a result, the middleware short-circuits the execution and returns 401 before the Endpoint.RequestDelegate has a chance to run, which would have returned the appropriate 4xx status code as normally expected.

I agree that it might seem a little strange since you're expecting the other status codes, but this does seem to be the correct and expected behavior. From a pure security perspective, the current behavior is certainly more secure. If the authorization assertion did not short-circuit the request pipeline with 401, it would allow probing with API versions. That is a non-issue for publicly disclosed APIs, but if you wanted an API hidden, indicating 400, 405, and so on would advertise that the endpoint does indeed exist, but not for that API version. That may not be something you're concerned about, but that's my best rationale for why things behave the way they do.

I'm not sure there is a simple or straight forward way to change this behavior if you're still not satisfied with it, but I'm open to ideas.

[MGessinger]

Correct if me if I'm wrong, but from the perspective of a client application, getting a 401 suggests that may succeed if different credentials are supplied. If the request is rejected because the provided API version is "wrong" (in some broad sense of the word), that's not the case. No amount of credentials will ever make that request succeed.
That's not specific to the setup described in the original post; I would never expect 401 (or 403, for that matter) when the request fails because of the version.
What I'm getting at is the idea of adding IAllowAnonymous metadata to the UnspecifiedApiVersionEndpoint. That way, no authorization setup will short circuit the request, and the error code should reflect what actually went wrong.

Regarding the security aspect, this certainly permits probing for versions (e.g. requesting version 1 returns 401 but requesting version 1.1 returns 400 => 1.0 is implemented but 1.1 is not) but is that really an issue? What information would you gain?

[commonsensesoftware]

@MGessinger you're correct with respect to the behavior of 401 and 403. The conflating part is that the authorization middleware is enforcing the policy regardless of endpoint. With the curtains pulled back, the white box interpretation might seem strange because you know you'll get a 400 or 404 anyway. I'm not sure I am, or ever would be, overall concerned about version probing, but it's certainly possible; especially, if the versions are advertised.

I can get onboard with allowing anonymous access to failure endpoints, but for consistency, they should behave the same way as other endpoints that would short-circuit this way. This should include 404 (or something that really doesn't exist), 405, 415 and maybe even 406, which I know isn't enforced until the response is ready to be served.

One of the trickier behaviors is that if the API version is unsupported or unspecified, then that should mean we don't know what the target endpoint is nor its security posture. If 404 doesn't trigger the 401 response challenge, then I think it's ok to apply the anonymous metadata to all of the failure endpoints. They have very functionally similar behaviors. If the 401 behavior is triggered, then there probably needs to be some type of option that allows it. Agree or disagree with what the behavior ought to be, I wouldn't want to change the security posture in a way that is a surprise for service owners. This is a behavioral change that is likely to go unnoticed from a library package update.

[commonsensesoftware]

Following up, I did a quick test and as far as I can see, you'll get 401 for any normal 404 endpoint. As a concrete example, I was able to dig up the 405 logic here:

https://github.com/dotnet/aspnetcore/blob/7a2262da483f193a7bb1cb1f82289983fe4a1461/src/Http/Routing/src/Matching/HttpMethodMatcherPolicy.cs#L392

You can see that the Endpoint is generated dynamically and has no metadata. In both of these cases, if you were to send:

GET /fake HTTP/2

or

POST /foo?api-version=1.0 HTTP/2

You'll get 401. This happens before any of API Versioning's routing even gets involved. There are some edge cases where API Versioning could do what is being proposed; for example:

GET /foo?api-version=2.0 HTTP/2

but I think this would be confusing. In some cases, you'll get 401 and other cases you'll get 400.

Given this information, I'm not inclined to change the current behavior, but I'll give you a chance to convince me if you believe otherwise.

[MGessinger]

Ah, I see where I went wrong now. The authorization check essentially says "require an authorized request, unless the chosen endpoint says otherwise."
In the case at hand, there is no chosen endpoint and so there is no anonymous access. The fact that there would have been an endpoint with anonymous access, if the request had specified a different version, is too many "ifs" and "would" and "had" for one sentence.
You're right that this is intended behavior:

• Request comes in
• try to identify an enpoint, based on route and API version
• no endpoint is found
• does the chosen endpoint allow bypassing the autorization? No because there is no endpoint!
• 401

Makes sense!