Add document explaining the authentication system

[davidfowl]

Requests for new Topics

Write a short paragraph describing what the topic will cover.

Today our authentication documentation is scenario focused. This is fine but doesn't help explain the fundamentals of the system and the various component responsibilities. We should have an introduction to the authentication system that describes the services (IAuthentictation* interfaces), the verbs (challenge, authentication, forbid, signin, signout), what authentication schemes are, what authentication handlers are etc. There should also be diagrams of a typical authentication flow with all of the actors involved.

2. Write an outline of the proposed topic contents.

Here's an example of what I think this topic could look like: https://digitalmccullough.com/posts/aspnetcore-auth-system-demystified.html

3. Where would you put the topic in the Table of Contents.

https://docs.microsoft.com/en-us/aspnet/core/security/authentication/

4. If you know who should review the issue, notify them by including @githubID in the issue description.

@HaoK @blowdart @Tratcher

[HaoK]

@Rick-Anderson is there someone on the doc side that I can work with for this new topic?

[Rick-Anderson]

@scottaddie can you work with Haok on this?

[davidfowl]

@HaoK I'd like these sorts of samples as part of the doc https://github.com/leastprivilege/AspNetCoreSecuritySamples/tree/aspnetcore2. Credit goes to @leastprivilege 😄

[HaoK]

@davidfowl how do you feel about Authentication.Cookies/JWT/etc in entropy as the official home for the samples that the documents will reference?

[Tratcher]

No, the docs have their own copy of the samples they reference.

[HaoK]

Ok, but I'll still put MVC + auth sample reference apps similar to Dominick's in entropy, since the security ones can't depend on MVC

[Tratcher]

We've also had asks for a demo on dynamically adding and removing auth schemes.

[Tratcher]

See https://github.com/aspnet/Security/blob/0959c941b40086b131b1e01d304fc23bb887fdc8/test/Microsoft.AspNetCore.Authentication.Test/DynamicSchemeTests.cs#L137-L143

[HaoK]

@scottaddie we went ahead and created an official home for the AuthSamples, they will be slowly coming online here: https://github.com/aspnet/AuthSamples

We can tailor the samples towards what this doc needs as well. We still need to figure out how to deal with the keys/cred issue for the auth providers that require external setup (OAuth/OIDC).

[HaoK]

@scottaddie a new sample showing how to dyamically add schemes and update their options has been added here: https://github.com/aspnet/AuthSamples/tree/dev/samples/DynamicSchemes

@Rick-Anderson edit: Samples moved to https://github.com/aspnet/AspNetCore/tree/master/src/Security/samples

[Rick-Anderson]

@scottaddie how about doing this is phases?

• Create a page that links to the samples
• Create article.

[scottaddie]

@Rick-Anderson I'm okay with that approach.

[Rick-Anderson]

@HaoK Is the start of https://digitalmccullough.com/posts/aspnetcore-auth-system-demystified.html good enough that I should reach out to the author and ask him make the first PR? We could use our samples.

[Rick-Anderson]

See Add some documentation for claims transformation (Auth) #2097

[Rick-Anderson]

Per @JamesNK in #13764

There is no article that gives an overview of authentication in ASP.NET Core.

The article should talk about:

What authentication is What authentication options there are An introduction to setting up authentication It should be located at: Security and Identity -> Authentication -> Overview

Equivalent page for authorization: https://docs.microsoft.com/en-us/aspnet/core/security/authorization/introduction