Merge pull request #743 from DuendeSoftware/mb/replay

Improve clarity in refresh tokens documentation

Author: maartenba

src/content/docs/bff/fundamentals/blazor/index.md

@@ -38,7 +38,7 @@ These rendering modes are very powerful, but also add additional complexity when
 For more information on this, see [rendering-modes](/bff/fundamentals/blazor/rendering-modes)
 
 ### Authentication State
-The **AuthenticationState ** contains information about the currently logged-in user. This is partly populated from information from the user, but is also enriched with several management claims, such as the Logout URL. 
+The `AuthenticationState` contains information about the currently logged-in user. This is partly populated from information from the user, but is also enriched with several management claims, such as the Logout URL. 
 
 Blazor uses AuthenticationStateProviders to make authentication state available to components. On the server, the authentication state is already mostly managed by the authentication framework. However, the BFF will add the Logout url to the claims using the **AddServerManagementClaimsTransform**.  On the client, there are some other claims that might be useful. The **BffClientAuthenticationStateProvider** will poll the server to update the client on the latest authentication state, such as the user's claims. This also notifies the front-end if the session is terminated on the server. 
 

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

@@ -73,7 +73,7 @@ Refresh tokens are a high-value target for attackers, because they typically hav
 tokens.
 
 However, refresh tokens for _confidential clients_ are bound to that client; they can only be used by the client they
-are issued to and the client is required to authenticate itself in order to do so. An attacker able to obtain a refresh
+are issued to and the client is required to authenticate itself to do so. An attacker able to obtain a refresh
 token issued to a confidential client cannot use it without the client's credentials.
 
 Refresh tokens issued to public clients are not bound to the client in the same way, since the client cannot
@@ -132,15 +132,15 @@ avoids those writes.
 
 To make one time use tokens more robust to network failures, you can customize the behavior of the `RefreshTokenService`
 such that consumed tokens can be used under certain circumstances, perhaps for a small length of time after they are
-consumed. To do so, create a subclass of the `DefaultRefreshTokenService` and override its *AcceptConsumedTokenAsync(
-RefreshToken refreshToken)* method. This method takes a consumed refresh token and returns a boolean flag that indicates
+consumed. To do so, create a subclass of the `DefaultRefreshTokenService` and override its `AcceptConsumedTokenAsync(
+RefreshToken refreshToken)` method. This method takes a consumed refresh token and returns a boolean flag that indicates
 if that token should be accepted, that is, allowed to be used to obtain an access token. The default implementation in
 the `DefaultRefreshTokenService` rejects all consumed tokens, but your customized implementation could create a time
 window where consumed tokens can be used.
 
 New options added In 6.3 interact with this feature. The `PersistentGrantOptions.DeleteOneTimeOnlyRefreshTokensOnUse`
 flag will cause OneTime refresh tokens to be deleted on use, rather than marked as consumed. This flag will need to be
-disabled in order to allow a customized Refresh Token Service to use consumed tokens.
+disabled to allow a customized Refresh Token Service to use consumed tokens.
 
 Consumed tokens can be cleaned up by a background process, enabled with the existing
 `OperationalStoreOptions.EnableTokenCleanup` and `OperationalStoreOptions.RemoveConsumedTokens` flags. Starting in 6.3,
@@ -157,22 +157,35 @@ builder.Services.TryAddTransient<IRefreshTokenService, YourCustomRefreshTokenSer
 
 ### Replay Detection
 
-In addition to one-time only usage semantics, you might wish to add replay detection for refresh tokens. If a refresh
-token is configured for one-time only use but used multiple times, that means that either the client application is
-accidentally mis-using the token (a bug), a network failure is preventing the client application from rotating
-properly (see above), or an attacker is attempting a replay attack. Depending on your security requirements, you might
-decide to treat this situation as an attack, and take action. What you might do is, if a consumed refresh token is ever
-used, revoke all access for that client/user combination. This could include deleting refresh tokens, revoking access
-tokens (if they are introspection tokens), ending the user's server side session, and sending back-channel logout
-notifications to client applications. You might also consider alerting the user to suspicious activity on their account.
+In addition to one-time only usage semantics, you can add replay detection for refresh tokens.
+Multiple uses of a one-time-only refresh token may indicate:
+
+* A client application bug
+* Network failure during token rotation
+* A potential replay attack
+
+Depending on your security requirements, you can treat this situation as an attack, and take action.
+If a consumed refresh token is ever used, you could revoke all access for that client/user combination.
+This could include deleting refresh tokens, revoking access tokens (if they are introspection tokens),
+ending the user's server side session, and sending back-channel logout notifications to client applications.
+You can also consider alerting the user to suspicious activity on their account.
+
+:::caution
 Keep in mind that these actions are disruptive and possibly alarming to the user, and there is a potential for false
 positives.
+:::
+
+While replay and re-use detection can be useful, they can be tricky to implement. In load-balanced environments,
+some form of synchronization will be required to avoid race conditions.
+
+Implementing replay detection can be done in a similar way to [accepting consumed tokens](#accepting-consumed-tokens). Extending the
+`AcceptConsumedTokenAsync` method of the `DefaultRefreshTokenService`, you can add the additional revocation or alerting
+behavior that you choose. Depending on your scenario, overriding the `CreateRefreshTokenAsync`,
+`ValidateRefreshTokenAsync` and `UpdateRefreshTokenAsync` methods may also be desired.
 
-Implementing replay detection is similar to [accepting consumed tokens](#accepting-consumed-tokens). Extend the
-`AcceptConsumedTokenAsync` method of the `DefaultRefreshTokenService` and add the additional revocation or alerting
-behavior that you choose. In 6.3, the same new options that interact with accepting consumed tokens also interact with
-replay detection. The `PersistentGrantOptions.DeleteOneTimeOnlyRefreshTokensOnUse` flag needs to be disabled so that
-used tokens persist and can be used to detect replays. The cleanup job should also be configured to not delete consumed
+The options that interact with accepting consumed tokens also interact with replay detection.
+The `PersistentGrantOptions.DeleteOneTimeOnlyRefreshTokensOnUse` flag needs to be disabled so that used tokens persist 
+and can be used to detect replays. The cleanup job should also be configured to not delete consumed
 tokens.
 
 See also: The [IRefreshTokenService](/identityserver/reference/services/refresh-token-service.md) reference.