search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.63k stars 25.3k forks source link

Document the claims actions #5106

Closed kevinchalet closed 5 years ago

kevinchalet commented 6 years ago

Moved from https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers/issues/210.

While a sample can be found in the aspnet/Security repository, there's currently no formal documentation for the "claims actions" APIs offered by the OAuth-based providers in ASP.NET Core 2.x.

/cc @Tratcher @guardrex

Rick-Anderson commented 6 years ago

@PinpointTownes is this something you could write with some help? @Tratcher or @HaoK would you be able to write the first draft?

HaoK commented 6 years ago

This one is all @Tratcher :)

Tratcher commented 6 years ago

https://github.com/aspnet/Security/pull/1124 for reference. I can write a doc outline.

kevinchalet commented 6 years ago

@Rick-Anderson I'll leave that to @Tratcher. After all, he's the one who designed this API :smile:

Tratcher commented 6 years ago

When using a remote auth providers like Oauth, Facebook, OpenIdConnect, etc. user information is provided from the service in a JSON blob. That information needs to be mapped to Claims in a ClaimsIdentity for consumption by the rest of the application. Auth handlers like the Facebook handler map a few claims by default such as name and e-mail address. They don't try to map everything by default because they don't want to make the auth cookie too large.

Prior to 2.0 the recommended way to customize the claims mapping process was to hook into the OnCreatingTicket (Oauth) or OnUserInformationReceived (OIDC) events, inspecting the JSON, and creating your own claims. If you didn't like the claims the framework had mapped for you then you needed to use this event to remove them from the identity. Example: https://stackoverflow.com/a/35634697/2588374. This would still be worth documenting for advanced scenarios.

We realized that most of these mappings were very mechanical, mapping one JSON key to one Claim. In 2.0 we added ClaimActions as a way to handle simple or customized mappings. The auth handler options (e.g. OAuthOptions https://github.com/aspnet/Security/blob/226b24060f72a7d63e6a6f8f3eaeb4dc5a909fe5/src/Microsoft.AspNetCore.Authentication.OAuth/OAuthOptions.cs#L96) have a ClaimActions collection property. A few actions are added by default https://github.com/aspnet/Security/blob/226b24060f72a7d63e6a6f8f3eaeb4dc5a909fe5/src/Microsoft.AspNetCore.Authentication.Facebook/FacebookOptions.cs#L36 and the developer can remove these and/or add their own in Startup https://github.com/aspnet/Security/blob/226b24060f72a7d63e6a6f8f3eaeb4dc5a909fe5/samples/SocialSample/Startup.cs#L106-L107. Each time a user authenticates with this auth handler these actions are run.

The frameworks provides some common actions and extension methods for creating and adding them to the collection. https://github.com/aspnet/Security/tree/dev/src/Microsoft.AspNetCore.Authentication.OAuth/Claims Users can define custom actions by deriving from ClaimAction and implementing the abstract Run method. https://github.com/aspnet/Security/blob/226b24060f72a7d63e6a6f8f3eaeb4dc5a909fe5/src/Microsoft.AspNetCore.Authentication.OAuth/Claims/ClaimAction.cs#L40

There's some confusion between ClaimActions.Remove("foo") and .DeleteClaim("foo"). Remove removes an action of the given name from the collection. DeleteClaim deletes a claim of the given type from the identity. Delete is primarily used with OIDC to remove protocol generated claims. https://github.com/aspnet/Security/blob/226b24060f72a7d63e6a6f8f3eaeb4dc5a909fe5/src/Microsoft.AspNetCore.Authentication.OpenIdConnect/OpenIdConnectOptions.cs#L47

Rick-Anderson commented 5 years ago

@PinpointTownes can you fix the following links?

While a sample can be found in the aspnet/Security repository, there's currently no formal documentation for the "claims actions" APIs offered by the OAuth-based providers in ASP.NET Core 2.x.

Can you suggest where this should be documented?

Tratcher commented 5 years ago

https://github.com/aspnet/Security/blob/26d27d871b7992022c082dc207e3d126e1d9d278/samples/CookieSample/Startup.cs https://github.com/aspnet/Security/tree/26d27d871b7992022c082dc207e3d126e1d9d278/src/Microsoft.AspNetCore.Authentication.OAuth/Claims

It would go somewhere under the auth node: https://docs.microsoft.com/en-us/aspnet/core/security/authentication/samples?view=aspnetcore-2.2 I don't see an existing page it belongs in, it applies to all the OAuth providers as well as OpenIdConnect.

guardrex commented 5 years ago

Sorry ... I must have missed this one in spite of the ping.

there's currently no formal documentation for the "claims actions" APIs offered by the OAuth-based providers in ASP.NET Core 2.x.

What about :point_right: https://docs.microsoft.com/aspnet/core/security/authentication/social/additional-claims

Tratcher commented 5 years ago

Oh, it's is mentioned here: https://docs.microsoft.com/en-us/aspnet/core/security/authentication/social/additional-claims?view=aspnetcore-2.2#map-user-data-keys-and-create-claims

guardrex commented 5 years ago

@Rick-Anderson @Tratcher The sample associated with that topic is coming up for my 2.2 round of sample updates (it's currently a 2.1 sample). If you want me to add more content to it to cover additional scenarios, ~you can let me know what's MIA here~ ([EDIT] looks like everything is here, I should be fine with the remarks above) and assign this to me. I'll knock it out when I get to that sample update, which should be fairly soon ... within a few weeks.