.NET 7 - Add documentation about Identity SecurityStampValidator

[HaoK]

There's been an app building exercise around auth in 7.0, and that resulted in some feedback that we currently don't have any documentation about Identity's SecurityStamp / single sign out functionality. I'll put the first draft of the content in this issue, but I wasn't sure exactly where this content should go, maybe a new link under authentication called Identity SIgnOut Everywhere?

ISecurityStampValidator and SignOut everywhere

Sometimes your application does something that changes a user in such a way that its appropriate to regenerate a User's ClaimsPrincipal (joining a role, changing a password, or other security sensitive actions). The ISecurityStampValidator is the interface that Identity uses to accomplish this. The default implementation of Identity registers a SecurityStampValidator with the main application cookie, as well as the two factor cookie. The validator hooks into the OnValidatePrincipal event of each cookie to call into Identity to verify that the user's SecurityStamp claim is unchanged from what's stored in the cookie, at regular intervals (tradeoff between hitting the database and stale claims). Whenever your app wants to force existing cookies to be invalid the next time they are checked, simply call userManager.UpdateSecurityStampAsync(user), this is what most of the Identity UI account/manage pages do after changing the password/adding a login. This is also how apps can easily implement a SignOut everywhere action.

Changing the validation interval can be done via:

// Force Identity's security stamp to be validated every minute
builder.Services.Configure<SecurityStampValidatorOptions>(o => o.ValidationInterval = TimeSpan.FromMinutes(1));

cc @rafikiassumani-msft @blowdart @Tratcher @DamianEdwards @adityamandaleeka for feedback (should I elaborate more on the mechanics?)

[DamianEdwards]

*** Edit by @Rick-Anderson to add links*** Great to see this! We have a section in the Use cookie authentication without ASP.NET Core Identity doc titled React to back-end changes that covers similar scenarios when not using Identity. I think that title is good as it's related to a scenario rather than an interface name or concept. Can we somehow incorporate that aspect here too so folks looking for how to force claims validation/reauthentication/etc. can easily find it in the Identity doc?

[GeoJGH]

On this topic, it would be nice to be explicit about the fact that calling Services.AddDefaultIdentity() / Services.AddIdentity() will register the cookie events with OnValidatePrincipal = SecurityStampValidator.ValidatePrincipalAsync, and therefore if we use a custom options.EventsType = typeof(CustomCookieAuthenticationEvents), the securitystamp validation will not occur. In such case, one must call await SecurityStampValidator.ValidatePrincipalAsync(context); inside the CustomCookieAuthenticationEvents

public class CustomCookieAuthenticationEvents : CookieAuthenticationEvents
{
    public async override Task ValidatePrincipal(CookieValidatePrincipalContext context)
    {
        await SecurityStampValidator.ValidatePrincipalAsync(context);
        
        //optional custom code
    }
}

PS: stackoverflow post