Generic OpenIdConnect and OAuth concept docs

[Tratcher]

We have walkthrough docs for things like WsFed, AAD, and Facebook OAuth. E.g. https://docs.microsoft.com/en-us/aspnet/core/security/authentication/ws-federation?view=aspnetcore-2.1

However OAuth and even more so OpenIdConnect are not provider specific, we should provide a dedicated doc for each showing how you can use the various features of these generic auth components to work with a variety of auth providers.

RE: https://github.com/aspnet/Security/pull/1776#pullrequestreview-128444394

[Rick-Anderson]

@Tratcher can you suggest someone to draft the doc?

[Tratcher]

Me or @PinpointTownes 😁

[Tratcher]

Regarding generic OAuth: The Microsoft.AspNetCore.Authentication.OAuth package has common components used to develop provider specific authentication handlers (e.g. Facebook, Microsoft, etc..). However, the base OAuth2 components can also be used directly if implementing a derived handler is not desired.

There are two different levels of direct use. The first level can be used to get access tokens without any user claims (claims retrieval is not part of the OAuth2 standard). To do this you need to supply the fields shown in this sample. Refer to your provider's documentation for the appropriate endpoint URLs.

If you also need to retrieve user information you can fill in the provider specific retrieval code in the OnCreatingTicket event, as well as the ClaimActions for mapping that information to claims.

This doc might also serve as a good place for documenting common features like ClaimActions, SaveTokens, CallbackPath, etc..

OpenIdConnect is an improvement upon OAuth2 that among other things standardizes claims retrieval. This allows the OpenIdConnect auth handler to be used directly with many providers with minimal configuration code. Here are some examples (though many are using 1.x). http://docs.identityserver.io/en/release/quickstarts/3_interactive_login.html https://stormpath.com/blog/openid-connect-user-authentication-in-asp-net-core https://jonhilton.net/2017/05/10/secure-you-asp-net-core-mvc-and-web-api-app-using-google/ https://grean.com/easyid/aspnetcore/oidc/2017/06/15/vs2017-aspnetcore-easyid.html https://developer.okta.com/blog/2017/06/29/oidc-user-auth-aspnet-core https://andrewlock.net/an-introduction-to-openid-connect-in-asp-net-core/

Key OpenIdConnect settings to mention (beyond the OAuth settings above):

• Authority
• GetClaimsFromUserInfoEndpoint
• ResponseMode
• ResponseType
• AuthenticationMethod
• UseTokenLifetime
• Prompt
• Scope

[Rick-Anderson]

@PinpointTownes would you be able to provide the first draft? Let me know how I can help.

[Rick-Anderson]

@serpent5 is this something you could do?

[serpent5]

I've got a couple of other issues to look at now but I'll come back and check the status of this once I'm done with those.