AzureADDefaults.JwtBearerAuthenticationScheme vs AzureADDefaults.BearerAuthenticationScheme

[SaebAmini]

The docs mention that on the server-side, we should add authentication via

services.AddAuthentication(AzureADDefaults.BearerAuthenticationScheme)

But since it's using JWT, shouldn't it be the JWT scheme instead?

services.AddAuthentication(AzureADDefaults.JwtBearerAuthenticationScheme)

The guide seems to be switching between the two schemes throughout the guide which is also a bit confusing. Are these two schemes actually interchangeable?

---

Document Details

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

• ID: 3039ff79-ee86-20b1-0082-d3899a84c823
• Version Independent ID: af4a3a75-ae52-5f6d-2120-737bc2fefb07
• Content: Secure an ASP.NET Core Blazor WebAssembly hosted app with Azure Active Directory
• Content Source: aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory.md
• Product: aspnet-core
• Technology: aspnetcore-blazor
• GitHub Login: @guardrex
• Microsoft Alias: riande

[guardrex]

Hello @SaebAmini ... Those are two different auth methods for different purposes ... cookie vs. JS. The topic isn't switching ... it only indicates that for the JwtBearerOptions configuration that the scheme is AzureADDefaults.JwtBearerAuthenticationScheme. Azure's default scheme for Azure Active Directory Bearer is AzureADDefaults.BearerAuthenticationScheme. I think we have some general coverage over in the Authorize with a specific scheme topic (and probably in a few other general security topics) ... see if that helps. If you need to ask general questions on security, this isn't the best spot ... we're a very small team that just works on docs here. You can consult with devs on the usual support channels. We recommend ...

• Stack Overflow
• ASP.NET Core Slack
• ASP.NET Gitter

[SaebAmini]

So why is this guide using two auth schemes? it seems to be constantly talking about the JWT scheme in the text, while just one piece of code is using BearerAuthenticationScheme. Thanks for introducing me to StackOverflow! but this isn't a "general security question", it's an issue I find with your docs, which TBH on the topic of auth are notorious.

[guardrex]

Two auth schemes because authenticating users against Azure AD uses one scheme, while the API calls to the server API (coming from MSAL/JS in the client) uses the other scheme.

I wouldn't characterize the topic as constantly mentioning the "JWT scheme." It mentions JWT in a few spots. I do agree that none of the reasoning for the setup/configuration is explained in detail. This doc is a 'how to' ... more of a tutorial ... than a reference topic that seeks to explain the services and API in detail. Those concepts are general security concepts for Azure AD/API as far as this topic is concerned.

I will keep an eye out for feedback asking for more detail. If we get more feedback, then I'll see if I can quickly add more info. Right now, it's best to leave this topic focused on the setup/config and not get too deep into the weeds.

When I remarked that you should ask general questions on support channels, I meant if you wanted to discuss security concepts generally. I apologize for the way that it's phrased. It's literally a saved reply in GitHub that we use. Discussions generate a lot of pings on this repo that distract from actionable doc issues. We have ~500 issues for over 400 topics and 100 sample apps with only four doc authors 🏃😅. Therefore, we often request and suggest the chats and SO for general discussion. It's just a stock recommendation that we make. It wasn't specific for this issue.

[SaebAmini]

Rex, you know we all love you mate ❤. I've always been impressed with how you do an amazing job answering all the issues raised here so quickly and with so much helpful information. Sorry I got a bit grouchy with the canned response. I think the main reason was not that I expected to find all the information in this "how-to" or get them from you, but that the information in other places is also so fragmented and hard to find - I couldn't really find any good reference docs either.

For example, do a Google search for the two auth schemes above and a search for JwtBearerAuthenticationScheme in your own Microsoft docs. Not much comes up and the only thing in Google that comes up from MS Docs is the above Blazor page.

I know for you guys who are intimately familiar with all of this stuff and are in close contact with the teams that have built them, these might be obvious questions. But I'm just saying, finding specific information on auth in your docs is pretty difficult and the info is so fragmented and I know many peeps who share the same feeling.

I understand the team is small and can't deal with general questions; maybe having some reference links below these "how-to" articles for people who want to find out/delve more into some of the topics could help with that?

[YuxuanLin]

Hi @guardrex !

Thank you for explaining the concepts and that shades a bit more information for us to learn and understand. Actually I run into the same issue and spend days to figure out how-to for my case.

You replied:

Those are two different auth methods for different purposes ... cookie vs. JS.

Questions:

1. What is JS? Javascript?

2. Which is for cookie? And does it mean that validate a cookie containing a jwt?

3. I tested in my code using context.HttpContext.AuthenticateAsync(scheme); in custom attribute. For bearer authentication(bearer jwt in header) those two AzureADDefaults.JwtBearerAuthenticationScheme AzureADDefaults.BearerAuthenticationScheme are interchangeable. In another way both of them works on the jwt bearer header anthentication. So what is exactly the difference between those two?

Thank you very much!!
Best

[SaebAmini]

Months later, I come across the same article and this very issue @guardrex.

I know your team is shorthanded and busy, but again, I have to disagree that this is a general security question and believe you've closed it in error. This is about types in the AzureADDefaults class, the Microsoft.AspNetCore.Authentication.AzureAD.UI package, and ASP.NET Core's documentation (or lackthereof) of the why and differences between them.

The guide says:

The AddAuthentication method sets up authentication services within the app and configures the JWT Bearer handler as the default authentication method. The AddAzureADBearer method sets up the specific parameters in the JWT Bearer handler required to validate tokens emitted by the Azure Active Directory:

Followed by a line of code that then sets AzureADDefaults.BearerAuthenticationScheme as the default:

services.AddAuthentication(AzureADDefaults.BearerAuthenticationScheme)

... okay, what's going on? as a reader I'm confused here. See, your library also has a AzureADDefaults.JwtBearerAuthenticationScheme (which is used further down the article), it raises the question for me on why it's not using, well, the JWT scheme in the code since it's claiming we're setting that, and what's the difference between these two schemes and how they are handled. If these are not interchangeable, this has to be an error either in the text, or the code.

Let's look at the the advertised auth schemes topic - well that makes perfect sense and is clear as it's using two distinct and well named schemes (JwtBearerDefaults.AuthenticationScheme and CookieAuthenticationDefaults.AuthenticationScheme), but nothing on the difference between the schemes mentioned here.

Let's search for these scheme names, but other than this very GitHub issue and code, not much else comes up. At this point the only way to understand the difference on what these really mean and how they differ is only digging in the code and that's a gap in documentation. That gap might be in ASP.NET Core land, Identity land, or just simple XML code documentation, but it's a gap.

Re the explanation that one is for cookies and one for JS, I'm assuming you meant BearerAuthenticationScheme is for cookies and JwtBearerAuthenticationScheme for JWT, but why not just use CookieAuthenticationDefaults.AuthenticationScheme for cookies? or have some useful documentation on BearerAuthenticationScheme explaining that? what is it bearing? why would I use one over the other?

[guardrex]

Let me get back to you next week @SaebAmini ... As you know, .NET 5 just released. I'm still playing catch-up with some bits (the AAD groups and roles guidance for Identity v2.0/5.0). I'm fairly focused on that for the next few days into next week. I've left your issue ping in my Inbox, so I won't lose track of this. I might open a new issue based on a fresh analysis. I'll get back to you as soon as I can ... I think no later than the end of next week. 🏃⛏️⛰️😅

EDIT ... I just re-opened this issue. That's best.

[udlose]

any updates on this issue? I also have the same question. TIA

[guardrex]

Nothing yet outside of my original answers ☝️, which I think are correct. As I mentioned earlier, you can converse with security pros further on the usual support channels, and there are other docs in MS Security & Identity and provided by the community that may help. I'll get to this issue as soon as I can, but I'm still 🏃😅⛰️⛏️ on high priority issues.

• Stack Overflow (tag: blazor)
• ASP.NET Core Slack Team
• Blazor Gitter

[guardrex]

I'll be closing this now ...

• The coverage will either be cross-links to existing coverage outside of the Blazor docs node (we have some updated ASP.NET Core coverage now and Microsoft Identity Platform docs have improved quite a bit since their first release of docs) or new coverage in the Blazor docs node ... but only what's absolutely necessary and specific to Blazor scenarios.
• This issue will be addressed on the UE ("user experience," i.e., total overhaul) passes of the Blazor security topics. I've made a note to review this issue and Explain schemes in Blazor WASM security #19807. I hope to reach the Blazor security node in early 2022 🤞.