"Authentication and authorization in minimal APIs" documentation unclear configuration options

[laurencee]

I was testing out setting up JWT bearer auth for a minimal .NET 7 API without using my own options/configuration section by trying to follow the documentation on this page: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/security?view=aspnetcore-7.0#configuring-authentication-strategy

I ended up getting the following validation failure on the bearer token when calling an endpoint Bearer was not authenticated. Failure message: IDX10501: Signature validation failed. Unable to match key. The issue in this case was the Authority not being set on the options (the error message isn't particularly helpful).

I ended up having to look at the source code for the JwtBearerConfigureOptions class to find out how I could configure this setting.

I think the documentation sample should be updated to include/reference this options class (or all the properties loaded from config into it) so developers know what values can be defined in configuration.

Furthermore, the example on that minimal API page should probably be updated to define the Authority property, as that's the most common configuration used when setting up JWT bearer auth to my understanding.

When using a user defined custom config section/option, the auth configuration usually looks something like this:

builder.Services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        }).AddJwtBearer(options =>
        {
            var jwtOptions = builder.Configuration.GetRequiredSection("MyJwtSettings").Get<MyJwtOptions>();
            ArgumentNullException.ThrowIfNull(jwtOptions);
            options.Authority = jwtOptions.Issuer;
            options.Audience = jwtOptions.Audience;
        });

If the framework provided option is configured correctly in appsettings you do not need the above and can simply do builder.Services.AddAuthentication().AddJwtBearer();

---

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

• ID: 3a9d7eb8-6c1f-4619-00fa-9b69dbe3dcea
• Version Independent ID: 3a9d7eb8-6c1f-4619-00fa-9b69dbe3dcea
• Content: Authentication and authorization in minimal APIs
• Content Source: aspnetcore/fundamentals/minimal-apis/security.md
• Product: aspnet-core
• Technology: aspnetcore-fundamentals
• GitHub Login: @captainsafia
• Microsoft Alias: safia

[Rick-Anderson]

@captainsafia please review. @laurencee Thanks for reporting this. Any chance you could PR this? At the top right of the article, select the Edit pen icon:

Select the pen icon again. Edit, then Save.

Or maybe help me get it updated?

[laurencee]

Thanks for the prompt response @Rick-Anderson

I never knew the articles were editable like that, if I get some time on the weekend I'll see if I can come up with something for this.

Do you have a proposal for how we should reference the available properties that can be set in the app configuration? Something like "For a full list of available configuration options for JWT bearer based authentication, please refer to the mappings in this class file" ?

The primary benefit of that approach is the code is the single source of truth for how the mapping is actually done.

[Rick-Anderson]

Something like

For a full list of available configuration options for JWT bearer based authentication, see the JwtBearerConfigureOptions class.

[laurencee]

I've given it a go and sent through a PR, so let me know what you think when you get the time.