Update the 5.0 -> 6.0 migration guide to include a section about the claim issuer changes

guides/migration/50-to-60.md

@@ -12,11 +12,11 @@ For that, update your `.csproj` file to reference the `OpenIddict` 6.x packages.
 
 ```xml
 <ItemGroup>
-  <!-- OpenIddict 4.x: -->
+  <!-- OpenIddict 5.x: -->
   <PackageReference Include="OpenIddict.AspNetCore" Version="5.8.0" />
   <PackageReference Include="OpenIddict.EntityFrameworkCore" Version="5.8.0" />
 
-  <!-- OpenIddict 5.x: -->
+  <!-- OpenIddict 6.x: -->
   <PackageReference Include="OpenIddict.AspNetCore" Version="6.0.0-rc1.24608.69" />
   <PackageReference Include="OpenIddict.EntityFrameworkCore" Version="6.0.0-rc1.24608.69" />
 </ItemGroup>
@@ -118,6 +118,64 @@ As part of this change, the `OpenIddictConstants.Prompts` class have been rename
 and `OpenIddictRequest.HasPromptValue()` to match the names used in this specification. If you're using these APIs, make sure you're
 updating the corresponding calls when migrating to OpenIddict 6.0.
 
+## React to the claim issuer changes in the client stack
+
+Starting with 6.0, OpenIddict now allows customizing the claims issuer used to populate the `Claim.Issuer` and `Claim.OriginalIssuer`
+properties (this option is specially useful when using the OpenIddict client in legacy ASP.NET 4.6.2+ applications using ASP.NET Identity,
+since the `Claim.Issuer` property is directly reflected in the user interface):
+
+```csharp
+options.AddRegistration(new OpenIddictClientRegistration
+{
+    // ...
+
+    Issuer = new Uri("https://localhost:44395/", UriKind.Absolute),
+    ClaimsIssuer = "Local authorization server"
+});
+```
+
+```csharp
+options.UseWebProviders()
+       .AddActiveDirectoryFederationServices(options =>
+       {
+           // ...
+
+           options.SetClaimsIssuer("Contoso");
+       });
+```
+
+As part of this change, the OpenIddict client now uses `OpenIddictClientRegistration.ProviderName` instead of the issuer URI as the first
+fallback value when `OpenIddictClientRegistration.ClaimsIssuer` is not explicitly set, which is consistent with the pattern used in the
+OAuth 2.0-based social providers developed by Microsoft and the community (if no provider name was set, the issuer URI is used as the
+claims issuer, as in previous versions).
+
+If your code relies on a specific `Claim.Issuer` or `Claim.OriginalIssuer` value, you'll need to either update it to match the new logic or
+set `ClaimsIssuer` (or call `options.SetClaimsIssuer()` for a web provider) so that the registration uses the issuer URI as the claims issuer:
+
+```csharp
+options.AddRegistration(new OpenIddictClientRegistration
+{
+    // ...
+
+    Issuer = new Uri("https://localhost:44395/", UriKind.Absolute),
+    ClaimsIssuer = "https://localhost:44395/"
+});
+```
+
+```csharp
+options.UseWebProviders()
+       .AddFacebook(options =>
+       {
+           // ...
+
+           options.SetClaimsIssuer("https://www.facebook.com/");
+       });
+```
+
+> [!TIP]
+> The complete list of providers with their issuer URIs can be found here:
+> https://github.com/openiddict/openiddict-core/blob/dev/src/OpenIddict.Client.WebIntegration/OpenIddictClientWebIntegrationProviders.xml
+
 ## If applicable, migrate to `MongoDB.Driver` version 3.0
 
 To fix a breaking change introduced by the MongoDB in their 2.x branch, the `OpenIddict.MongoDb` and `OpenIddict.MongoDb.Models`
@@ -129,7 +187,7 @@ OpenIddict users relying on the MongoDB integration will also need to update the
 > the minimum version: projects referencing the `OpenIddict.MongoDb` or `OpenIddict.MongoDb.Models` packages and targeting
 > .NET Standard 2.0 or .NET Framework < 4.7.2 will have to be updated when migrating to OpenIddict 6.0.
 
-## If applicable, updated your checks to ensure authenticated identities are correctly identified (OWIN only)
+## If applicable, update your checks to ensure authenticated identities are correctly identified (OWIN only)
 
 In OpenIddict 6.0, the ASP.NET Core and OWIN integrations now include the authentication properties attached to
 `ProcessAuthenticationContext.Properties` in errored authentication results, which is useful when used with the client stack