[Authentication] Add Information if/how we should implement Refresh Token Handler in ASP.NET Core

[DevTKSS]

Description

first of all, appreciate the improved docs for this topic and want to thank the team/eventual contributors that enabled this👍

The only point I am now missing and was unable to find this in the other auth related docs for asp net core too, is the Refresh Tokens.
What I found:

• https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/security?view=aspnetcore-9.0
  • Does not tell anything about cookie/oAuth then only JWT 🤔 my client is a native application so I guess that would not work/not be recommended.
• https://learn.microsoft.com/en-us/aspnet/core/security/authentication/cookie?view=aspnetcore-9.0#create-an-authentication-cookie
  • We have IsPersistant Explained here, which would be wrong for this in my opinion
  • SlidingExpiration 🤔 I would assume this is relyable for providing the expires_at/ExpiresUtc
  • context.ShouldRenew() -> I don't know if this is what could do this already automatically? I only found one single mention without future explaination of it at the end of react to backend changes chapter 🤔
• https://learn.microsoft.com/en-us/answers/questions/2262907/how-to-get-access-token-and-refresh-token-from-in
  • this makes me assume, that this may not apply for general usage if I dont use Entra or MS Identity for example then want to implement cookie auth via external provider.

Google search told me, that Asp Net Core does not provide a build in way for refreshing tokens, which is okay (while not the simplest way I as user would like ;) ) but in this case it would be awesome if you could consider:

• adding a short Note giving us a clear statement and by this making us aware of that we need to implement it ourselfs
• if you would be really nice, you would provide a sample for how the Refresh Token Handler could look as minimalistic approach 👍

Page URL

https://learn.microsoft.com/en-us/aspnet/core/security/authentication/social/social-without-identity?view=aspnetcore-6.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/security/authentication/social/social-without-identity.md

Document ID

e64816f4-3391-5aab-31c2-ab4f915bc7f6

Platform Id

01676421-707c-f0a9-639c-a29a785cbe93

Article author

@serpent5

Metadata

• ID: 6f9d7ad5-47d6-80bf-88fe-fac3a74151a3
• PlatformId: 01676421-707c-f0a9-639c-a29a785cbe93
• Service: aspnet-core
• Sub-service: security

[wadepickett]

@DevTKSS, you are right, this could be improved. Thanks for filing the issue.

[wadepickett]

AI Analysis Report

Run by: @wadepickett as test on Copilot instruction for pre-review analysis suggestions for new issues.
Date: 2025-12-08
Issue: #36404
Model: GitHub Copilot

Issue Analysis: [Authentication] Add Information if/how we should implement Refresh Token Handler in ASP.NET Core

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

The user requests that the ASP.NET Core documentation (specifically for "Social sign-in authentication without ASP.NET Core Identity") clarify whether there is built-in or recommended support for refresh tokens and their management, especially for cookie-based or external provider (OAuth) authentication. The doc currently mentions SaveTokens (saving access and refresh tokens) but does not explain:

• Whether refresh token renewal/rotation should be managed by the developer, or
• How to implement a handler pattern for refreshing tokens.

The user suggests adding a note clarifying the expected user responsibility and, if possible, a minimal sample of a custom refresh token handler.

📁 Affected Files

File	Path	Lines	Section
Main article	aspnetcore/security/authentication/social/social-without-identity.md	55-66	"Save the access token"

📝 Proposed Changes

Documentation Updates

File: aspnetcore/security/authentication/social/social-without-identity.md
Location: Just after the explanation and code for SaveTokens (after line 66: "To retrieve a saved token, use AuthenticationTokenExtensions.GetTokenAsync...")
Type: New [!NOTE] block and (optionally) a minimalistic code example link

Current content (lines 55-66):

## Save the access token

<...>
To save access and refresh tokens after a successful authorization, set `SaveTokens` to `true` in `Program.cs`:

:::code language="csharp" source="social-without-identity/samples/6.x/SocialWithoutIdentitySample/Snippets/Program.cs" id="snippet_SaveTokens" highlight="12":::

To retrieve a saved token, use <xref:Microsoft.AspNetCore.Authentication.AuthenticationTokenExtensions.GetTokenAsync%2A>. The following example retrieves the token named `access_token`:

:::code language="csharp" source="social-without-identity/samples/6.x/SocialWithoutIdentitySample/Snippets/Pages/Privacy.cshtml.cs" id="snippet_OnGetAsync" highlight="3-4":::

Proposed change:

[!NOTE]
While ASP.NET Core provides facilities to save access and refresh tokens obtained from external providers, it does **not** provide built-in logic to automatically handle refresh token expiration or renewal. If your app needs to use long-lived access, you are responsible for:
- Detecting when the access token expires (typically via an authenticated API call failure or known expiry metadata).
- Using the saved refresh token to request a new access token from your external provider's token endpoint.
- Storing the updated tokens (by updating the authentication ticket/cookie or similar mechanism).

For more information and a sample of a custom refresh token handler, see [Manual refresh token management with ASP.NET Core](https://github.com/dotnet/AspNetCore.Docs/issues/36404#issuecomment-customsample) _(replace with actual sample/PR location if provided)_.

Optionally, append a minimal code sample showing how to intercept an expired access token, redeem a refresh token, and update the user's auth cookie. The sample should be concise and generic for cookie auth scenarios.

🎯 Action Plan

1. Edit file: aspnetcore/security/authentication/social/social-without-identity.md

   • Navigate to lines 55-66
   • After the "Save the access token" section (right after token retrieval code block)
   • Insert a new [!NOTE] block as above, clarifying the absence of built-in refresh logic

2. (Optional) Add code sample: Consider linking (or embedding) a minimal refresh handler sample (in the repo or as gist), showing:

   • Detection of expired access token
   • Using refresh token to obtain a new access token
   • Updating the auth ticket/cookie with new tokens

3. Label the Issue: Set ai-reviewed-issue-reported-action-plan label

⚠️ Considerations

• The update should be clearly marked as a clarification, not a feature change.
• Ensure the note is present across all .NET Core versions where SaveTokens is documented.
• Review related topics/pages (Cookie authentication, OAuth concepts) for consistency.
• If publishing a code sample, clearly distinguish between guidance for ASP.NET Core and provider-specific logic (e.g., Google, Microsoft, etc.).

🔗 References

• Published article: Social sign-in without Identity (Microsoft Learn)
• Source file: social-without-identity.md
• Related issue: #36404
• Storing tokens with SaveTokens (MS Docs)
• ASP.NET Core External Authentication Docs (MS Docs)

[DevTKSS]

@wadepickett I would like to add a suggestion that could be checked for possible sample code reuse-ability, which is until now not linked or sourced via Code Snippet like [code-csharp [] in docfx:

• https://github.com/dotnet/aspnetcore/blob/a9aaa320f1c4c771b2dee8c000409a5f04397339/src/Security/Authentication/samples/SocialSample/Startup.cs

Relevant Information would for example be for oAuth, which we only have API docs so far, no core guide itself for usage e.g. with Minimal API, as issued here:

• [Authentication] How to: Remote Authentication using oAuth2 ? #35842 - possibly, in case the page we are speaking about here is indeed meant to provide the oAuth2 relevant information that are missing there, then the naming in the TOC "Configure Social Authentication" is potentially causing miss-understandment problems on User-Side like mine, as this implicit assumption might not be the case for ALL oAuth Authentication using API's.
  Just for example, I would implement OAuth to the Etsy (E-Commerce Marketplace) API, then this is defintly nothing I would understand as social like with Google / Facebook etc.
• Why I am thinking that this TOC Item is possibly wrong named, is for example, that we do not have any link from the OIDC TOC Entry / Page here to the current page then only linking OAuth to the standards, which does absolutly not help implementing a own provider that doesn't exist into ASP.NET Core, while this page here is essentially about OAuth Providers. We are only missing that very core content for that case of no-provider exists, telling how to set up a handler, and contain a link to Additional claims + the Refresh Token Handler part somewhere of course.
• Simple Auth guide which still uses Controllers / Razor should get made available for Minimal API in the future. Heared of you are migrating your samples? Would be awesome to have it on that list 🚀
• our page does only so far tell about the schemes in the first section, but nobody tells us, if we have / what are the default routes that are used if not set for cookie based social logins:
  

Yes I know that you work in teams ( theirs is shining with no-progress since months 🤷 😅 ) so I given that you might not be able to "just" add also a link to this docs here from their issued Page, could you please check out the TOC Entries for the Social Auth? Took me a while to even find them, because I am not attempting to implement ASP.NET Core Identity to my Application then oAuth + JWT (to client apps like desktop) and now I would guess, someone forgot to move those nodes possibly?

• Social Providers (boxed in screenshot) should get their place nested to Configure Social Authentication (this page we are speaking of as Parent TOC Node
• Refactor their contents if there is even Identity specifics included (Google for example does not from what I see)
• only introduce in the Identity articles the specifics the Users need to do for impementing them into identity.

Feel free to add additional seperate issues if needed