Skip to content

Commit 1ec5470

Browse files
committed
Remove deprecated v8.0 cookie name migration details from docs
1 parent 0a7a8de commit 1ec5470

3 files changed

Lines changed: 1 addition & 67 deletions

File tree

astro/src/content/docs/identityserver/aspnet-identity/schemes.md

Lines changed: 0 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,6 @@ When a user logs in, their identity is established and persisted across requests
1616

1717
When using IdentityServer without ASP.NET Identity, the default cookie scheme is named `"idsrv"`, though we recommend using the constant `IdentityServerConstants.DefaultCookieAuthenticationScheme` in your code if you ever need it.
1818

19-
Starting in **v8.0**, the default cookie name (not the scheme name) has changed to `"__Host-idsrv"` to improve security. The scheme name remains `"idsrv"`. See [Cookie Name Migration (v8.0)](#cookie-name-migration) below for upgrade instructions.
20-
2119
The default cookie scheme is configured by default in `AddIdentityServer()`, which sets up the cookie authentication handler with this scheme name. This cookie is essential for:
2220

2321
- maintaining the user's authenticated session
@@ -59,8 +57,6 @@ This allows your login logic to read the claims from the external provider befor
5957

6058
IdentityServer always uses the `"idsrv.external"` scheme here, available in the `IdentityServerConstants.ExternalCookieAuthenticationScheme` constant.
6159

62-
Starting in **v8.0**, the default cookie _name_ for this scheme has changed to `"__Host-idsrv.external"` (previously `"idsrv.external"`). See [Cookie Name Migration (v8.0)](#cookie-name-migration) below for upgrade instructions.
63-
6460
### Check Session Cookie
6561

6662
IdentityServer session management requires a separate cookie to monitor the session state without sending the large authentication cookie.
@@ -70,24 +66,6 @@ The [User Session Service](/identityserver/reference/services/user-session-servi
7066

7167
Note this cookie is not marked as `HttpOnly`, so it can be accessed in client-side code. The JavaScript code that is required to check user sessions in the background also requires access to this cookie, and needs it to be `HttpOnly`.
7268

73-
## Cookie Name Migration :badge[v8.0]
74-
75-
In IdentityServer v8.0, the default cookie **names** changed to use the `__Host-` prefix for
76-
improved security. The `__Host-` prefix restricts cookies to HTTPS-only, `Path=/`, and no `Domain`
77-
attribute — providing defense-in-depth against cookie theft and session fixation attacks.
78-
79-
| Cookie | Old name (v7.x) | New name (v8.0) |
80-
| -------------------- | ---------------- | ----------------------- |
81-
| Primary auth cookie | `idsrv` | `__Host-idsrv` |
82-
| External auth cookie | `idsrv.external` | `__Host-idsrv.external` |
83-
84-
The authentication **scheme names** (`"idsrv"` and `"idsrv.external"`) are unchanged.
85-
86-
A migration middleware is available to transparently re-issue old cookies under the new names,
87-
and the cookie names can be overridden via `AuthenticationOptions`. See the
88-
[upgrade guide](/identityserver/upgrades/v7_4-to-v8_0.md#cookie-names-changed-to-__host--prefix)
89-
for full migration instructions.
90-
9169
## Common Pitfalls
9270

9371
- **Mixing Schemes:** Attempting to `SignOutAsync("idsrv")` when ASP.NET Identity is in use will have no effect on the actual `"Identity.Application"` cookie, leaving the user logged in. Always use the constants or the helper services (like `SignInManager`) that match your configuration.

astro/src/content/docs/identityserver/reference/options.md

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,7 @@ Login/logout related settings. Available on the `Authentication` property of the
283283

284284
- **`CookieAuthenticationScheme`**
285285
Sets the cookie authentication scheme configured by the host used for interactive users. If not set, the scheme will be inferred from the host's default authentication scheme. This setting is typically used when AddPolicyScheme is used in the host as the default scheme.
286+
286287
- **`CookieLifetime`**
287288

288289
The authentication cookie lifetime (only effective if the IdentityServer-provided cookie handler is used). Defaults to 10 hours.
@@ -295,14 +296,6 @@ Login/logout related settings. Available on the `Authentication` property of the
295296

296297
Specifies the SameSite mode for the internal cookies. Defaults to None.
297298

298-
- **`CookieName`** (added in `v8.0`)
299-
300-
Sets the name of the primary IdentityServer authentication cookie. Defaults to `"__Host-idsrv"`. The `__Host-` prefix enforces that the cookie is only sent over HTTPS, with `Path=/` and no `Domain` attribute. Set to `"idsrv"` to use the legacy cookie name when upgrading from a previous version.
301-
302-
- **`ExternalCookieName`** (added in `v8.0`)
303-
304-
Sets the name of the external/temporary authentication cookie. Defaults to `"__Host-idsrv.external"`. The `__Host-` prefix enforces that the cookie is only sent over HTTPS, with `Path=/` and no `Domain` attribute. Set to `"idsrv.external"` to use the legacy cookie name when upgrading from a previous version.
305-
306299
- **`RequireAuthenticatedUserForSignOutMessage`**
307300

308301
Indicates if user must be authenticated to accept parameters to end session endpoint. Defaults to false.

astro/src/content/docs/identityserver/upgrades/v7_4-to-v8_0.md

Lines changed: 0 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -247,43 +247,6 @@ HTTP 303 (See Other) for redirects from POST endpoints, in compliance with
247247
No action is needed unless you explicitly set `UseHttp303Redirects = false` in a previous version.
248248
If so, remove that setting — the redirect behavior can no longer be changed.
249249

250-
### Cookie Names Changed to `__Host-` Prefix
251-
252-
The default cookie names have changed in v8.0:
253-
254-
| Cookie | Old name (v7.x) | New name (v8.0) |
255-
| -------------------- | ---------------- | ----------------------- |
256-
| Primary auth cookie | `idsrv` | `__Host-idsrv` |
257-
| External auth cookie | `idsrv.external` | `__Host-idsrv.external` |
258-
259-
The `__Host-` prefix is a browser security feature that restricts the cookie to HTTPS-only
260-
connections, forces `Path=/`, and disallows a `Domain` attribute.
261-
262-
**Migrating existing sessions**: Use the migration middleware to transparently accept both old and
263-
new cookie names. Call it once per cookie, **before** `UseIdentityServer()`, in your `Program.cs`:
264-
265-
```csharp
266-
// Program.cs — add BEFORE UseIdentityServer()
267-
app.MigrateIdentityServerCookieName("idsrv", "__Host-idsrv");
268-
app.MigrateIdentityServerCookieName("idsrv.external", "__Host-idsrv.external");
269-
app.UseIdentityServer();
270-
```
271-
272-
This middleware is a transient migration aid. When a user visits with an old cookie, the middleware
273-
transparently re-issues it under the new name. Once all active sessions have been re-issued, you can
274-
remove the middleware calls.
275-
276-
You can also override the defaults using the new `AuthenticationOptions` properties:
277-
278-
```csharp
279-
// Program.cs
280-
builder.Services.AddIdentityServer(options =>
281-
{
282-
options.Authentication.CookieName = "my-custom-cookie";
283-
options.Authentication.ExternalCookieName = "my-custom-cookie.external";
284-
});
285-
```
286-
287250
### IClientStore.GetAllClientsAsync Now Required
288251

289252
`IClientStore` now includes a second required method:

0 commit comments

Comments
 (0)