Aspnetcore.docs: Persisting additional claims and tokens from external providers

[Tratcher]

When signing up for your application with an external provider (e.g. Facebook), the developer may want to persist additional data about the user, as well as their access and refresh tokens.
@HaoK @blowdart @danroth27

There are at least three parts to this process.
A. Extracting additional information from the provider and storing it as claims. The information is provider specific, but there is a generic pattern. In 1.x the developer hooks into an event on the auth middeware, reads the user info blob, and creates new claims for the temp cookie. For 2.0 the developer no longer needs to hook into the events to do this manually, there is a new ClaimActions list on the options that lets them add and remove mappings. See OAuthOptions.ClaimActions, OpenIdConnect.ClaimActions and TwitterOptions.ClaimActions.
B. Persisting access tokens in the temporary cookie. See RemoteAuthenticationOptions.SaveTokens.
C. When you get to the account controller, you need to copy this information into the user database on app sign-up, or optionally update it per sign-in.

[Rick-Anderson]

@Tratcher can you create a 2.0 sample that does this. We'll write a doc using the sample code.

[Tratcher]

@HaoK can you do part C?

[HaoK]

Sure

[Rick-Anderson]

@HaoK consider using the in-memory DB.

[HaoK]

See https://github.com/aspnet/AuthSamples/tree/dev/samples/Identity.ExternalClaims

[guardrex]

Updated sample link: https://github.com/aspnet/AuthSamples/tree/master/samples/Identity.ExternalClaims

The engineering sample is based on Google, so I'll also base the docs sample on Google.

[guardrex]

@Rick-Anderson @scottaddie I propose to place this under the security/authentication/social node ...

https://docs.microsoft.com/aspnet/core/security/authentication/social/

... at the bottom of the TOC node list, under the Other authentication providers topic.

Sound good?

Call it: external-claims.md

[scottaddie]

@guardrex That location sounds good to me.

I suggest that we also rename the Enable authentication using Facebook, Google, and other external providers ToC node. How about something shorter like External providers? It's already clear that we're talking about authN, since it lives under the Authentication ToC node.

[guardrex]

ToC node (toc.md) ...

Enable authentication using Facebook, Google, and other external providers

... to ...

External providers

Will do. :+1:

[guardrex]

mmm ... 🤔 ... I don't like "external claims" ... they aren't "external." How about ...

Title: Persist additional claims and tokens from external providers in ASP.NET Core
UID: security/authentication/social/additional-claims
File name: additional-claims.md
TOC node: Additional claims

[guardrex]

@HaoK ... You're the boss! Your sample 🎸 _ROCKS!_ 🎷

Works perfectly OOB. That makes writing on this subject sooooooooo easy. :beers:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/gender
male

I just checked that here locally ... _Yes!_ ... They're right! :smile: lol

[HaoK]

Cool, that was the hope and idea behind the auth samples :)

[guardrex]

@HaoK Found this at https://developers.google.com/+/web/api/rest/oauth ...

For login purposes, use the profile or https://www.googleapis.com/auth/plus.login scope. The https://www.googleapis.com/auth/plus.me scope is not recommended as a login scope because, for users who have not upgraded to Google+, it does not return the user's name or email address.

I'm moving from https://www.googleapis.com/auth/plus.me to https://www.googleapis.com/auth/plus.login, but let me know if that's a bad move.

I'm trying to work out now the scopes for the main providers. If you already know what they are, plz let me know. It's hand-to-hand combat with crappy 3rd party docs trying to discover them.

| Provider  | Scope |
| --------- | ----- |
| Facebook  | `` |
| Google    | `https://www.googleapis.com/auth/plus.login` |
| Microsoft | `` |
| Twitter   | `` |

[guardrex]

@HaoK Here are some wild guesses just for a few laughs :smile: ... I'll tentatively put them in until we sort this out.

| Provider  | Scope |
| --------- | ----- |
| Facebook  | `https://www.facebook.com/dialog/oauth` |
| Google    | `https://www.googleapis.com/auth/plus.login` |
| Microsoft | `https://login.microsoftonline.com/common/oauth2/v2.0/authorize` |
| Twitter   | `https://api.twitter.com/oauth/authenticate` |

[HaoK]

Sounds good, if you get a chance can you file a issue (or a PR) to update the auth samples? Unfortunately I don't really remember any of the details the providers anymore its been (many) years...

[guardrex]

Since I'm wildly speculating from online sources, it would be best if I verify these.

Time is a factor tho. If I don't get this topic done within 24 hours, management might take me out behind the chemical sheds and shoot me. :skull: lol

file a issue (or a PR) to update the auth samples

I checked for others besides Google, and I didn't find any, so it's just that one to update. I'll take care of it.

[HaoK]

Do what you need to ensure your survival :)

[guardrex]

I'm a bit surprised by this. The claim is mapped in the provider options ...

options.ClaimActions.MapJsonKey(ClaimTypes.Gender, "gender");

... but that's not enough. The claim has be added to the UserManager as well ...

await _userManager.AddClaimAsync(user, info.Principal.FindFirst(ClaimTypes.Gender));

... I'll cover it.

[HaoK]

Two different things, one brings it over to the external identity that identity reads from to link logins, you need to then store the claim value in the user's row (the AddClaim) for it to show up in the login cookie.

Yeah hence why this is a hot topic, not super straight forward to see how to flow everything

[HaoK]

We are still lacking a good end to end story here, its something we will eventually look at making better