Merge pull request #389 from DuendeSoftware/joe/v7-rc1

Update guide for v7 updated to rc1

IdentityServer/v7/docs/content/upgrades/v6.3_to_v7.0.md

@@ -4,15 +4,32 @@ weight: 40
 ---
 
 {{% notice note %}}
-This upgrade guide is work in progress based on the currently available [preview version of v7.0](https://github.com/DuendeSoftware/IdentityServer/releases/tag/7.0.0-preview.2).
+This upgrade guide is work in progress based on the currently available [release candidate of v7.0](https://github.com/DuendeSoftware/IdentityServer/releases/tag/7.0.0-rc.1).
 {{% /notice %}}
 
 ## What's New
-TODO
+IdentityServer v7.0 includes support for .NET 8, pushed authorization requests, OpenTelemetry metrics, cleanup job improvements, and many other fixes and enhancements. Please see our [release notes](https://github.com/DuendeSoftware/IdentityServer/releases/tag/7.0.0-rc.1) for complete details.
 
-## Step 1: Update NuGet package
+## Step 1: Update .NET Version
+In your IdentityServer host project, update the version of the .NET framework. For example in your project file:
 
-In your IdentityServer host project, update the version of the NuGet package reference. 
+```
+<TargetFramework>net6.0</TargetFramework>
+```
+
+would change to: 
+
+```
+<TargetFramework>net8.0</TargetFramework>
+```
+
+Any NuGet packages that you are using that target an older version of .NET should also be updated.
+For example, the version of *Microsoft.EntityFrameworkCore.SqlServer* or *Microsoft.AspNetCore.Authentication.Google* should be updated.
+Depending on what your IdentityServer host project is using, there may or may not be code changes based on those updated dependencies. 
+
+## Step 2: Update NuGet package
+
+In your IdentityServer host project, update the version of the Duende.IdentityServer package. 
 For example in your project file:
 
 ```
@@ -25,9 +42,17 @@ would change to:
 <PackageReference Include="Duende.IdentityServer" Version="7.0-preview.2" />
 ```
 
-## Step 2: Update Database Schema (if necessary)
 
-IdentityServer is abstracted from the data store on multiple levels, so the exact steps involved in updating your data store will depend on your implementation details. 
+## Step 3: Update Database Schema
+
+The schema updates required in this version are:
+- The server-side session entity in *Duende.IdentityServer.EntityFramework* now uses a 64-bit long as its primary key (previously was a 32-bit int).
+- Two new properties have been added to the client model for PAR support.
+   - *Client.RequirePushedAuthorization* is a new boolean property that controls if this client requires PAR. PAR is required if either the global configuration is enabled or if the client's flag is enabled (this can't be used to opt out of the global configuration). It is safe to initialize this column to false for existing clients, which will mean that the global configuration will be used.
+   - *Client.PushedAuthorizationLifetime* is a new nullable integer property that controls the lifetime of pushed authorization requests (in seconds) for a client. If this lifetime is set, it takes precedence over the global configuration. It is safe to initialize this column to *null* for existing clients, which means the global configuration is used.
+- A new table has been added to store pushed authorization requests. This new table contains a hashed identifier, the pushed parameters (as a string, serialized and data protected), and the expiration time of the request.
+
+IdentityServer is abstracted from the data store on multiple levels, so the steps involved in updating your data store will depend on your implementation details. 
 
 #### Custom Store Implementations
 The core of IdentityServer is written against the [store interfaces]({{<ref "reference/stores" >}}), which abstract all the implementation details of actually storing data. If your IdentityServer implementation includes a custom implementation of those stores, then you will have to determine how best to include the changes in the model in the underlying data store and make any necessary changes to schemas, if your data store requires that.
@@ -43,10 +68,9 @@ dotnet ef migrations add Update_DuendeIdentityServer_v7_0_preview_2 -c Configura
 dotnet ef migrations add Update_DuendeIdentityServer_v7_0_preview_2 -c PersistedGrantDbContext -o Migrations/PersistedGrantDb
 ```
 
-The ServerSideSession.Id property has been changed from `int` to `long`. The migrations created handles the data type change, but fails to drop and re-create the primary key. If the primary key constraint is not removed, running the migration fails. The primary key of the table needs to be dropped before the alter and then recreated. The easiest is to update the generated migrations file:
+The *ServerSideSession.Id* property has been changed from *int* to *long*. The generated migration handles the data type change but does not take into account that this column is the primary key for the table. If the primary key constraint is not removed, running the migration will fail. The primary key of the table needs to be dropped before the type is altered and then recreated. The easiest way to do so is to update the generated migration file:
 
 ```
-
 // Add this line before AlterColumn
 migrationBuilder.DropPrimaryKey("PK_ServerSideSessions", "ServerSideSessions");
 
@@ -67,10 +91,10 @@ migrationBuilder.AddPrimaryKey("PK_ServerSideSessions", "ServerSideSessions", "I
 ```
 
 {{% notice info %}}
- For most deployments the approach above will work. For deployments with high volumes of sessions, high availability demands and no low traffic hours this might be cause unacceptable downtime. The impact and possible workarounds depends on the database engine used.
+For most deployments the approach above will work. For deployments with high volumes of sessions, high availability demands and no low traffic hours this might cause unacceptable downtime. The impact and possible workarounds depend on the database engine used, but most databases include features for performing indexing operations and schema changes to an online system. Please consult your database's documentation or your DBA for more guidance.
 {{% /notice %}}
 
-Once you've updated the migration, they can be applied to your database:
+Once you've updated that migration, both migrations should be applied to your database:
 
 ```shell
 dotnet ef database update -c ConfigurationDbContext
@@ -80,8 +104,42 @@ dotnet ef database update -c PersistedGrantDbContext
 
 Some organizations prefer to use other tools for managing schema changes. You're free to manage your schema however you see fit, as long as the entities can be successfully mapped. Even if you're not going to ultimately use Entity Framework migrations to manage your database changes, generating a migration can be a useful development step to get an idea of what needs to be done.
 
-## Step 3: Breaking changes
-* A new interface *IIdentityServerTools* has been introduced for the *IdentityServerTools* helper class to allow mocking. Update any direct references to *IdentityServerTools* to *IIdentityServerTools*.
+## Step 4: Breaking changes
+
+#### Only impacts particular customizations or edge cases
+- The *DefaultCorsPolicyService* now depends on the *IConfigurationDbContext* directly, instead of taking a dependency on the *IServiceProvider* and resolving that DbContext from it. If you have a customized CORS implementation that derives from the *DefaultCorsPolicyService*, you need to update the constructor of your derived class to use the *IConfigurationDbContext*.
+- The *DPoPProofValidatonContext* has been refactored. Instead of the *Client* property, we now put the relevant details (expiration validation mode and clock skew) directly in the context. We also have added the HTTP method and URL to the context. If you have a custom implementation of the *IDPoPProofValidator* or a class that derives from the *DefaultDPoPProofValidator*, update your usage of the context appropriately.
+- The *DefaultTokenService* no longer includes an *IHttpContextAccessor*. This member was unused by the default implementation and marked as obsolete. Customizations that derive from the *DefaultTokenService* no longer need to pass the accessor to the base constructor. If such a customization needs the accessor, add it to the derived class.
+- The *ValidatedAuthorizeRequest.RequestedResourceIndiators* property was misspelled and has been renamed *RequestedResourceIndicators*.
+- The reference token store now includes the session id when revoking reference tokens. Implementors of *IReferenceTokenStore* should update their implementation of token revocation to include the session id.
+- Invalid prompt modes now cause validation errors that result in an HTTP 400 (Bad Request). Previously, invalid  prompt modes were ignored. This complies with updates to the OpenID Connect specification.
+- A new interface *IIdentityServerTools* has been introduced for the *IdentityServerTools* helper class to allow mocking. Update any direct references to *IdentityServerTools* to *IIdentityServerTools*.
+
+#### Newly Deprecated
+- *IAuthorizationParametersMessageStore* is deprecated. PAR is a more robust/standardized approach to get similar benefits.
+
+- The *IHttpContextAccessor* in the *EndSessionRequestValidator* is unused and has been marked as obsolete. It will be removed in a future version.
+
+#### Previously Deprecated, Now Removed
+- The obsolete *IdentityServerOrigin* constant has been removed. 
+- Several obsolete extension methods on *HttpContext* have been removed. These methods are replaced by methods in *IServerUrls* and *IIssuerNameService*. See #1457
+  - *HttpContext.GetSchemeSupportsSignOutAsync* is replaced by *IAuthenticationHandlerProvider.GetHandlerAsync* (you will also need to check if the handler implements *IAuthenticationSignOutHandler*).
+  - *HttpContext.GetIdentityServerOrigin* and *HttpContext.SetIdentityServerOrigin* are replaced by *IServerUrls.Origin*.
+  - *HttpContext.GetIdentityServerBasePath* and *HttpContext.SetIdentityServerBasePath* are replaced by *IServerUrls.BasePath*.
+  - *GetIdentityServerHost* is replaced by *IServerUrls.Origin*
+  - *GetIdentityServerBaseUrl* is replaced by *IServerUrls.BaseUrl*
+  - *GetIdentityServerRelativeUrl* is replaced by *IServerUrls.GetIdentityServerRelativeUrl*
+  - *GetIdentityServerIssuerUri* is replaced by *IIssuerNameService.GetCurrentAsync*
+  - *RedirectToAbsoluteUrl* is replaced by redirecting to a call to *IServerUrls.GetAbsoluteUrl*.
+- The obsolete and unused *IUserSessionExtensions* interface has been removed.
+- The obsolete *IPrincipal.GetName* and *IIdentity.GetName* extension methods have been removed. Use *ClaimsPrincipal.GetDisplayName* instead.
+- The obsolete *ResourceValidationRequest.IncludeNonIsolatedApiResources* has been removed. This flag was no longer used.
+
+#### Unlikely to impact anyone
+- The *KeyManagementOptions.SigningAlgorithms* is now an *ICollection* rather than an *IEnumerable*. If you are configuring signing algorithms using code, and setting the *SigningAlgorithms* to some type that implements *IEnumerable* but not *ICollection*, then you must change the type that you are using. In practice, we expect everyone uses a list or array (which are both *ICollections*).
+
+- The value of the constant *IdentityServerAuthenticationType* has changed from "IdentityServer4" to "Duende.IdentityServer". This constant is used as the value of the authentication type within the [ClaimsIdentity](https://learn.microsoft.com/en-us/dotnet/api/system.security.claims.claimsidentity.-ctor?view=net-7.0#system-security-claims-claimsidentity-ctor(system-security-principal-iidentity-system-collections-generic-ienumerable((system-security-claims-claim))-system-string-system-string-system-string)) that IdentityServer constructs. The authentication type's value is never used by IdentityServer or ASP.NET, so this is unlikely to impact anyone. It is also the name of the default cors policy created by IdentityServer. This could theoretically impact you if you have a CORS policy named "Duende.IdentityServer", as the new name now conflicts.
+
 
 ## Step 5: Done!