Merge pull request #697 from DuendeSoftware/mb/various

Various updates

Author: maartenba

src/content/docs/identitymodel-oidcclient/samples.md

@@ -20,9 +20,8 @@ show how to use a OidcClient with a variety of platforms and UI tools, including
 - [Windows Console Applications](https://github.com/IdentityModel/IdentityModel.OidcClient.Samples/tree/main/HttpSysConsoleClient) (relies on an HttpListener - a wrapper around the windows HTTP.sys driver)
 - [Windows Console Applications using custom uri schemes](https://github.com/IdentityModel/IdentityModel.OidcClient.Samples/tree/main/WindowsConsoleSystemBrowser)
 
-All samples use a demo instance of Duende.IdentityServer (https://demo.duendesoftware.com)
-as their OIDC Provider. You can see its source code
-[here](https://github.com/DuendeSoftware/demo.duendesoftware.com).
+All samples use a [demo instance of Duende IdentityServer](https://demo.duendesoftware.com)
+as their OIDC Provider. You can see its [source code on GitHub](https://github.com/DuendeSoftware/demo.duendesoftware.com).
 
 You can log in with *alice/alice* or *bob/bob*
 

src/content/docs/identityserver/apis/aspnetcore/confirmation.md

@@ -166,5 +166,5 @@ so you can supply the cache implementation of your choice. See the
 for more details on setting up distributed caches, along with many examples, including Redis, CosmosDB, and
 Sql Server.
 
-A full sample using the default in memory caching is available
-[here](https://github.com/DuendeSoftware/Samples/tree/main/IdentityServer/v7/DPoP).
+A full sample [using the default in memory caching](https://github.com/DuendeSoftware/Samples/tree/main/IdentityServer/v7/DPoP)
+is available on GitHub.

src/content/docs/identityserver/configuration/index.md

@@ -14,21 +14,15 @@ redirect_from:
 Added in Duende IdentityServer 6.3
 :::
 
-The Configuration API is a collection of endpoints that allow for management and
-configuration of an IdentityServer implementation. The Configuration API can be
-hosted either separately or within the IdentityServer implementation, and is
-distributed through the separate [Duende.IdentityServer.Configuration NuGet
-package](https://www.nuget.org/packages/Duende.IdentityServer.Configuration).
+The Configuration API is a collection of endpoints that allow for management and configuration of an IdentityServer
+implementation. The Configuration API can be hosted either separately or within the IdentityServer implementation, and is
+distributed through the separate [Duende.IdentityServer.Configuration NuGet package](https://www.nuget.org/packages/Duende.IdentityServer.Configuration).
 
-In this initial release, the Configuration API supports the [Dynamic Client
-Registration](/identityserver/configuration/dcr/) protocol. 
+In this initial release, the Configuration API supports the [Dynamic Client Registration](/identityserver/configuration/dcr/) protocol. 
 
-The Configuration API is part of the
-[IdentityServer](https://duendesoftware.com/products/identityserver) 
-Business Edition or higher. The same [license](https://duendesoftware.com/products/identityserver#pricing) 
+The Configuration API is part of the [IdentityServer](https://duendesoftware.com/products/identityserver) Business Edition or higher. The same [license](https://duendesoftware.com/products/identityserver#pricing) 
 and [special offers](https://duendesoftware.com/specialoffers) apply.
 
-The Configuration API source code is available [on
-GitHub](https://github.com/DuendeSoftware/products/tree/main/identity-server/src/Configuration).
+The Configuration API source code is available [on GitHub](https://github.com/DuendeSoftware/products/tree/main/identity-server/src/Configuration).
 
 Samples of the Configuration API are available [here](/identityserver/samples/configuration/).

src/content/docs/identityserver/tokens/client-authentication.md

@@ -31,7 +31,7 @@ Duende IdentityServer has built-in support for various client credential types a
 All information in this section also applies to [API secrets](/identityserver/reference/models/api-resource/) for introspection.
 :::
 
-**We recommend using asymmetric client credentials like the [*private key jwt*](#private-key-jwts) or [*Mutual TLS*](#mutual-tls-client-certificates) authentication method over shared secrets.**
+**We recommend using asymmetric client credentials like the [*private key JWT*](#private-key-jwts) or [*Mutual TLS (mTLS)*](#mutual-tls-client-certificates) authentication method over shared secrets.**
 
 ### Assigning Secrets
 
@@ -60,7 +60,7 @@ client.ClientSecrets = new[] { primary, secondary };
 ### Secret Parsing
 During request processing, the secret must be somehow extracted from the incoming request. The various specs describe a couple of options, e.g. as part of the authorization header or the body payload.
 
-It is the job of implementations of the [ISecretParser](/identityserver/reference/models/secrets#duendeidentityservervalidationisecretparser) interface to accomplish this. You can add secret parsers by calling the `AddSecretParser()` service provider extension method.
+It is the job of implementations of the [`ISecretParser`](/identityserver/reference/models/secrets#duendeidentityservervalidationisecretparser) interface to accomplish this. You can add secret parsers by calling the `AddSecretParser()` service provider extension method.
 
 The following secret parsers are part of Duende IdentityServer:
 
@@ -86,7 +86,7 @@ The following secret parsers are part of Duende IdentityServer:
 
 
 ### Secret Validation
-It is the job of implementations of the [ISecretValidator](/identityserver/reference/models/secrets.md#duendeidentityservermodelparsedsecret) interface to validate the extracted credentials.
+It is the job of implementations of the [`ISecretValidator`](/identityserver/reference/models/secrets.md#duendeidentityservermodelparsedsecret) interface to validate the extracted credentials.
 
 You can add secret validators by calling the `AddSecretValidator()` service provider extension method.
 

src/content/docs/identityserver/tokens/index.md

@@ -25,9 +25,10 @@ While the `authorize` endpoint can be used for some special cases, you typically
 The following token types are supported.
 
 ### Identity Token
-During user authentication, your IdentityServer collects data about the user, e.g. authentication method, authentication time, some protocol information and a unique identifier for the user that was authenticated, to communicate back to the client application “what happened at the token service”.
+During user authentication, your IdentityServer collects data about the user, e.g. authentication method, authentication time, some protocol information, and a unique identifier for the user that was authenticated.
+This data is used to communicate back to the client application “what happened at the token service”.
 
-This data must be sent in a format that is both tamper proof and that allows the client to authenticate the issuer. In OIDC this format is JSON – and the way to add the above security properties to a JSON object is by wrapping it in a JWT (along with JWS, JWA and JWK) – hence the name identity `token`.
+This data must be sent in a format that is both tamperproof and allows the client to authenticate the issuer. In OIDC this format is JSON. The way to add the above security properties to a JSON object is by wrapping it in a JWT (along with JWS, JWA, and JWK) – hence the name identity *token*.
 
 The data includes token lifetime information (`exp`, `iat`, `nbf`), the authentication method (`amr`) and time (`auth_time`), the authentication source (`idp`), the session ID (`sid`) and information about the user (`sub` and `name`).
 

src/content/docs/identityserver/ui/server-side-sessions/index.md

@@ -15,10 +15,8 @@ Added in Duende IdentityServer 6.1
 
 When a user logs in interactively, their authentication session is managed by the ASP.NET Core authentication system,
 and more specifically the cookie authentication handler.
-IdentityServer uses
-the [state in the cookie](/identityserver/ui/login/session#well-known-claims-issued-from-the-login-page) to track the
-user's subject and session identifiers (i.e. the `sub` and `sid` claims), and the list of clients the user has logged
-into (which is used at logout time for [OIDC logout notification](/identityserver/ui/logout/notification)).
+IdentityServer uses the [state in the cookie](/identityserver/ui/login/session#well-known-claims-issued-from-the-login-page) to track the user's subject and session identifiers (i.e. the `sub` and `sid` claims),
+and the list of clients the user has logged into (which is used at logout time for [OIDC logout notification](/identityserver/ui/logout/notification)).
 
 By default, this cookie is self-contained which means it contains all the state needed to track a user's session.
 While this does allow for a stateless server for session management, cookie size could be a problem, and it makes it
@@ -31,18 +29,15 @@ This implementation is specifically designed for IdentityServer to allow for mor
 querying for active sessions based on subject id or session id, and revoking artifacts from protocol workflows as part
 of that session.
 
-Support for Server Side Sessions is included in [IdentityServer](https://duendesoftware.com/products/identityserver)
-Business Edition or higher.
+Support for Server Side Sessions is included in [IdentityServer](https://duendesoftware.com/products/identityserver) Business Edition or higher.
 
 ## Session Management
 
 With the addition and use of server-side sessions, more interesting architectural features are possible:
 
 * the ability to query and [manage sessions](/identityserver/ui/server-side-sessions/session-management/) from outside the browser that a user is logged into.
-* the ability to detect [session expiration](/identityserver/ui/server-side-sessions/session-expiration/) and perform cleanup both in IdentityServer and
-  in the client.
-* the ability to centralize and monitor session activity in order to achieve a
-  system-wide [inactivity timeout](/identityserver/ui/server-side-sessions/inactivity-timeout/).
+* the ability to detect [session expiration](/identityserver/ui/server-side-sessions/session-expiration/) and perform cleanup both in IdentityServer and in the client.
+* the ability to centralize and monitor session activity to achieve a system-wide [inactivity timeout](/identityserver/ui/server-side-sessions/inactivity-timeout/).
 
 ### Enabling Server-side Sessions
 
@@ -56,9 +51,8 @@ builder.Services.AddIdentityServer()
 ```
 
 By default, the store for the server-side sessions will just be kept in-memory.
-For production scenarios you will want to configure a durable store either by using
-our [EntityFramework Core implementation](/identityserver/data/ef#operational-store), or you
-can [implement the store yourself](/identityserver/reference/stores/server-side-sessions/).
+For production scenarios you will want to configure a durable store either by using our [EntityFramework Core implementation](/identityserver/data/ef#operational-store),
+or you can [implement the store yourself](/identityserver/reference/stores/server-side-sessions/).
 
 :::note
 Order is important in the ASP.NET Core service provider.
@@ -69,26 +63,21 @@ has been registered.
 ### Data Stored Server-side
 
 The data stored for the user session is the data contained in the ASP.NET Core `AuthenticationTicket` class. This
-includes
-all claims and the `AuthenticationProperties.Items` collection. The `Items` can be used to store any custom (string)
+includes all claims and the `AuthenticationProperties.Items` collection. The `Items` can be used to store any custom (string)
 data. The `AuthenticationProperties` is included in the call to `SignInAsync` that establishes the user session in the
 UI code.
 
-This data will be serialized and protected using ASP.NET
-Core's [data protection](/identityserver/deployment#data-protection-keys) feature to protect any user PII from being
-directly readable in the data store.
-To allow querying some of the values from the user's session are extracted and used as indices in the store. These
-values are the user's:
+This data will be serialized and protected using ASP.NET Core's [data protection](/identityserver/deployment#data-protection-keys) feature to protect any user PII from being
+directly readable in the data store. To allow querying, values from the user's session are extracted and used as indices in the store.
+These values are the user's:
 
 * subject identifier (the `sub` claim value)
 * session identifier (the `sid` claim value)
 * display name (an optional and configurable claim value)
 
 If you would like to query this data based on a user's display name, then the claim type used is configurable with the
-`ServerSideSessions.UserDisplayNameClaimType` property on
-the [IdentityServerOptions](/identityserver/reference/options#authentication).
-This claim must be included in the claims when the
-user's [authentication session is established](/identityserver/ui/login/session).
+`ServerSideSessions.UserDisplayNameClaimType` property on the [`IdentityServerOptions`](/identityserver/reference/options#authentication).
+This claim must be included in the claims when the user's [authentication session is established](/identityserver/ui/login/session).
 
 For example:
 
@@ -101,9 +90,13 @@ builder.Services.AddIdentityServer(options => {
 
 ### IServerSideSessionStore
 
-The [`IServerSideSessionStore`](/identityserver/reference/stores/server-side-sessions) is the abstraction for storing
-the server-side session.
+The [`IServerSideSessionStore`](/identityserver/reference/stores/server-side-sessions) is the abstraction for storing the server-side session.
 
-A EntityFramework Core implementation is already provided as part of
-our [operational store](/identityserver/data/ef#operational-store), but you can implement
+An EntityFramework Core implementation is already provided as part of our [operational store](/identityserver/data/ef#operational-store), but you can implement
 the [interface](/identityserver/reference/stores/server-side-sessions/) yourself for other backing implementations.
+
+:::caution[Prefer `GetSessionsAsync` over `QuerySessionsAsync`]
+When listing sessions, prefer `GetSessionsAsync` over `QuerySessionsAsync`.
+The `QuerySessionsAsync` method performs a full-text search and may be slower to retrieve a list of sessions than `GetSessionsAsync`.
+Use `QuerySessionsAsync` only when more advanced filtering is required for the solution you are building.
+:::

src/content/docs/identityserver/ui/server-side-sessions/session-management.md

@@ -42,11 +42,11 @@ For example:
 
 ```cs
 var userSessions = await _sessionManagementService.QuerySessionsAsync(new SessionQuery
-    {
-        CountRequested = 10,
-        SubjectId = "12345",
-        DisplayName = "Bob",
-    });
+{
+    CountRequested = 10,
+    SubjectId = "12345",
+    DisplayName = "Bob",
+});
 ```
 
 The results returned contains the matching users' session data, and paging information (depending on if the store and backing database supports certain features such as total count and current page number).
@@ -56,24 +56,24 @@ This paging information contains a `ResultsToken` and allows subsequent requests
 ```cs
 // this requests the first page
 var userSessions = await _sessionManagementService.QuerySessionsAsync(new SessionQuery
-    {
-        CountRequested = 10,
-    });
+{
+    CountRequested = 10,
+});
 
 // this requests the next page relative to the previous results
 userSessions = await _sessionManagementService.QuerySessionsAsync(new SessionQuery
-    {
-        ResultsToken = userSessions.ResultsToken,
-        CountRequested = 10,
-    });
+{
+    ResultsToken = userSessions.ResultsToken,
+    CountRequested = 10,
+});
 
 // this requests the prior page relative to the previous results
 userSessions = await _sessionManagementService.QuerySessionsAsync(new SessionQuery
-    {
-        ResultsToken = userSessions.ResultsToken,
-        RequestPriorResults = true,
-        CountRequested = 10,
-    });
+{
+    ResultsToken = userSessions.ResultsToken,
+    RequestPriorResults = true,
+    CountRequested = 10,
+});
 ```
 
 

src/content/docs/identityserver/upgrades/identityserver4-v3-to-duende-identityserver-v6.md

@@ -13,19 +13,19 @@ redirect_from:
 ---
 
 This upgrade guide covers upgrading from IdentityServer4 v3.1.x to Duende IdentityServer v6.
-This upgrade is a complex one because the configuration object model had some non-trivial changes from IdentityServer4 v3 to IdentityServer4 v4.
+This upgrade is more complex because the configuration object model had some non-trivial changes from IdentityServer4 v3 to IdentityServer4 v4.
 
 In short, in IdentityServer4 v3 there was a parent-child relationship between the ApiResources and the ApiScopes.
 Then in IdentityServer4 v4 the ApiScopes was promoted to be its own top-level configuration. 
 This meant that the child collection under the ApiResources was renamed to ApiResourcesScopes and it contained a reference to the new top-level ApiScopes.
 
 If you were using a database for this configuration, then this means that configuration changed from a parent-child, to two top-level tables with a join table between them (to put it loosely). The new ApiResourcesScopes table was created to act as that join table.
 
-Also, all the prior tables that were associated with the ApiResources were prefixed with "Api" and that prefix became "ApiResource" to better indicate the association. 
+Also, all the prior tables associated with the `ApiResources` were prefixed with "Api" and that prefix became "ApiResource" to better indicate the association. 
 Then any new tables associated with the new top-level ApiScopes have the "ApiScope" prefix to indicate that association.
 
-In order to properly update the database, the easiest approach is to first update to the latest of IdentityServer4 v4. 
-Once that's complete, then it's very simple to move to Duende IdentityServer v5.
+To properly update the database, the easiest approach is to first update to the latest of IdentityServer4 v4. 
+Once that's complete, then it's straightforward to move to Duende IdentityServer v5.
 
 There is a sample project for this migration exercise. It is located [here](https://github.com/DuendeSoftware/UpgradeSample-IdentityServer4-v3).
 
@@ -50,7 +50,7 @@ If you're using any of the other IdentityServer4 packages, such as `IdentityServ
 
 If you are using a [database](/identityserver/data) for your configuration and operational data, then there is a bit of work.
 The reason is that for this type of schema restructuring EntityFramework Core's migrations can lose existing data.
-To handle this, the conversation from the old schema to the new will be performed by custom SQL.
+To handle this, custom SQL will perform the conversation from the old schema to the new.
 This is only needed for the configuration database, not the operational one so normal migrations will suffice for the operational database.
 
 First for the operational database, we can apply EF Core migrations.