diff --git a/guides/migration/50-to-60.md b/guides/migration/50-to-60.md index adfe1ef..e2891a8 100644 --- a/guides/migration/50-to-60.md +++ b/guides/migration/50-to-60.md @@ -12,11 +12,11 @@ For that, update your `.csproj` file to reference the `OpenIddict` 6.x packages. ```xml - + - + @@ -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