migrating-mvc-authentication

# ASP.NET MVC Authentication and Authorization Migration ## Overview Migrate authentication and authorization from ASP.NET MVC/Web API to ASP.NET Core. This is the highest-risk area of any ASP.NET migration because wrong decisions produce security vulnerabilities, not compiler errors. Multiple migration paths exist depending on the authentication mechanism used — assess first, then apply the correct path. > **Related skills:** For side-by-side Katana/ASP.NET Core shared cookies, see `sharing-authentication-cookies-katana-interop`. For ASP.NET Identity (UserManager, SignInManager, IdentityDbContext), see `migrating-aspnet-identity`. For OWIN cookie auth, see `migrating-owin-cookie-auth`. For OWIN OAuth/JWT, see `migrating-owin-oauth-to-jwt`. For OWIN OpenID Connect, see `migrating-owin-openid-connect`. For an endpoint that trades an external workload OIDC token for a short-lived application credential, see `migrating-federated-oidc-token-exchange`. For ADAL to MSAL, see `migrating-adal-to-msal`. ## Workflow ``` Migration Progress: - [ ] Step 1: Assess authentication mechanisms - [ ] Step 2: Migrate authentication configuration - [ ] Step 3: Migrate sign-in and sign-out calls - [ ] Step 4: Migrate membership and user stores - [ ] Step 5: Migrate authorization rules - [ ] Step 6: Migrate anti-forgery tokens - [ ] Step 7: Remove legacy references - [ ] Step 8: Build and verify ``` ### Step 1: Assess Authentication Mechanisms Scan the project to determine which authentication mechanisms are in use. Check these locations: - `web.config`: `<authentication mode="...">`, `<membership>`, `<roleManager>`, `<machineKey>`, `<authorization>` - `Global.asax` / `Startup.cs` / `Startup.Auth.cs`: OWIN middleware registration - Controllers and views: `FormsAuthentication.*`, `Membership.*`, `Roles.*`, `User.Identity.*` - Custom classes: `IPrincipal`, `IIdentity`, `MembershipProvider`, `RoleProvider` implementations Determine the deployment model before choosing a migration path: - **Full cutover:** the Framework host stops serving requests when the Core host starts. Continue with the replacement paths below. - **Side-by-side:** both hosts serve the same users during an incremental migration. Establish cross-app identity before migrating authenticated routes. The **Cross-App Cookie Authentication** upgrade option chooses the mechanism: `sharing-authentication-cookies-katana-interop` when it is **Shared Cookie (Data Protection interop)**, and `migrating-mvc-system-web-adapters` for **Remote Authentication** — the latter only while the **System.Web Adapters** option is **Use System.Web Adapters**, which is what loads that skill. Do not load the adapters skill for remote authentication when System.Web Adapters is **Direct Migration to ASP.NET Core APIs**; that would impose the whole shim overlay on a user who declined it. The interop skill takes precedence over the full-cutover cookie replacement guidance below. This gate applies whenever the deployment model is side-by-side **and** a .NET Framework host in the solution still authenticates browser requests with a cookie. Do not condition it on a **Cross-App Cookie Authentication** value appearing in the confirmed selections. Under either confirmed value the Core host takes its identity from the Framework host, and under *no* confirmed value the Framework host is still the one issuing the cookie — with `migrating-mvc-system-web-adapters` wiring remote authentication as its side-by-side default wherever that skill actually establishes the remote app connection. All of those states want the same thing from this skill: the Core host must not mint a competing cookie of its own. Gating on the confirmed set instead would leave the commonest absence case registering a Core cookie *and* receiving a remote authentication client — authenticating every request twice, with the redirect-loop risk the **Interactions** rules exist to prevent. A side-by-side migration whose Framework host does not authenticate browser requests with a cookie — a Windows-authenticated app, an API-only host, an anonymous one — is not covered by this gate and continues through the paths below normally. If the Core host turns out to have no way to obtain identity from the Framework host at all, that is a gap to report, not a reason to lift this gate. Registering a Core-issued cookie does not give the Core host the user's existing session; it gives it a second, unrelated one. There is exactly one release. If the operator, answering a conflict this migration reported, states that a session reset is acceptable — signed-in users signing in again at the host boundary — the gate lifts and the Core host registers its own cookie through the normal paths below. That has to be an explicit answer to a question that was actually put to them. Do not read it out of a missing **Cross-App Cookie Authentication** value, out of no mechanism being available, or out of risk prose written for a human reader: silence is not consent to sign every user out, which is the whole reason absence maps to a default instead. Say in the migration notes that the reset was accepted and that the resulting Core cookie is a second, unrelated session, so the decision is visible to whoever reads the change later. When the gate applies, the Framework host keeps issuing the authentication cookie. Skip: - **Step 2A** and `migrating-owin-cookie-auth`, which register a Core-issued cookie scheme. - **Step 3**, which rewrites `FormsAuthentication.SetAuthCookie` into `HttpContext.SignInAsync` on that scheme. With Step 2A skipped the scheme does not exist, and adding it back produces exactly the session reset the option exists to avoid. Sign-in and sign-out stay on the Framework host with the rest of the identity endpoints. - The **cookie registration** inside `migrating-aspnet-identity`. `AddIdentity()` registers the Identity cookie schemes; use `AddIdentityCore()` where the Core host needs the user store without them. - The **cookie and external-sign-in conversions** inside `migrating-owin-to-aspnet-core`. That skill rewrites `app.UseCookieAuthentication(...)` into `AddAuthentication().AddCookie(...)` and `app.UseExternalSignInCookie()` into `AddCookie()` plus an external provider. Both mint a Core-issued cookie. Its non-authentication work — the OWIN pipeline, middleware and startup conversion — is unaffected. - The **sign-in cookie** in `migrating-owin-openid-connect`. That route pairs `.AddOpenIdConnect()` with `.AddCookie()` and makes the cookie the default scheme, which is a Core-issued cookie by another name. An external-provider handshake is an identity endpoint: leave the OpenID Connect challenge and its callback on the Framework host, to migrate later with the rest of the identity endpoints. - The cookie-related removals in **Step 7** — see the note in that step. The Framework host is still issuing the cookie, so the code and configuration that issue it are still in use. Then apply the rule for the mechanism in play: - **Shared Cookie (Data Protection interop)** — `sharing-authentication-cookies-katana-interop` owns the cookie wiring and takes precedence over the full-cutover guidance below. - **Remote Authentication**, where `migrating-mvc-system-web-adapters` actually establishes the remote app connection — that skill loads, it applies to this host, and the host clears the .NET Framework 4.7.2 floor its remote-app package requires. The Framework host stays the identity authority. Do not introduce a Core-issued cookie scheme by any route; a Core host that mints its own cookie has not implemented remote authentication. - **Remote Authentication**, where nothing actually establishes it — no skill delivers that wiring step by step. Three cases land here: System.Web Adapters set to **Direct Migration to ASP.NET Core APIs**, which never loads that skill; a host that skill does not wire, such as an OWIN self-host with no System.Web application to shim; and a host pinned below the 4.7.2 floor, where that skill reports a blocking conflict instead of wiring. The remote-auth packages are separable from the shim overlay, but this product delivers their setup only through `migrating-mvc-system-web-adapters`. Stop at that boundary: hold the authenticated routes on the Framework host, migrate the anonymous ones, and say plainly that the remote-auth wiring is not covered step by step here. Still do not substitute a Core cookie scheme. The pairing is valid, so do not resolve it by changing either option's value on your own — report it, and name what would actually unblock it: the operator can re-plan with **Use System.Web Adapters** where the host can use it, lift the pin, qualify the host for **Shared Cookie (Data Protection interop)**, wire the remote-app packages by hand, or state that a session reset is acceptable and take the release above. - **No confirmed value** — treat it exactly as the two Remote Authentication cases above, and pick between them the same way: by asking whether `migrating-mvc-system-web-adapters` actually establishes the remote app connection, never by reading an option value. Where it does, its side-by-side default wires remote authentication and the two agree. Where it does not, the boundary rule applies unchanged. In both cases say plainly that no cross-app mechanism was confirmed, so the reader can see this followed a default rather than a choice. Do not read a session reset into the silence — but if the operator, once told that identity has no route across, states that a reset is acceptable, take the release above. Unaffected by the gate: the membership, role-provider and password-hashing paths (Step 4), Negotiate (Step 2B), and the authorization-policy work — they concern the user store and access rules, not the cookie. The **Success Criteria** at the end of this skill assume a full cutover; the bullets marked *(full cutover only)* there do not apply under this gate. The Framework host keeps issuing the cookie until the identity endpoints migrate as a unit. Categorize findings into one or more paths: | Signal | Migration Path | |--------|---------------| | `<authentication mode="Forms">`, `FormsAuthentication.*` | → Cookie Authentication (Step 2A) | | `SqlMembershipProvider`, `SimpleMembership`, custom `MembershipProvider` | → ASP.NET Core Identity (Step 4) | | `<authentication mode="Windows">` | → Negotiate Authentication (Step 2B) | | OWIN OAuth/JWT middleware | → See `migrating-owin-oauth-to-jwt` | | An endpoint that trades a caller-supplied external OIDC token (a CI or workload identity token) for a short-lived application credential, after matching its claims against a stored trust policy | → See `migrating-federated-oidc-token-exchange` | | OWIN cookie middleware | → See `migrating-owin-cookie-auth` | | OWIN OpenID Connect | → See `migrating-owin-openid-connect` | | Custom OWIN authentication scheme (a type deriving from the Katana `AuthenticationHandler<TOptions>`, usually with its own `AuthenticationMiddleware<TOptions>` and `IAppBuilder` extension) | → See `migrating-owin-authentication-handler-to-core` | | ASP.NET Identity (IdentityDbContext, UserManager) | → See `migrating-aspnet-identity` | Projects often combine multiple mechanisms (e.g., Forms Auth + Membership + Role Provider). Apply each relevant path. Under the side-by-side gate above, no route may leave the Core host issuing its own authentication cookie. Cookie Authentication (Step 2A) and the OWIN cookie route do not apply at all — the Framework host keeps issuing the cookie. Two routes in the table apply only in part, and the skip list above says which part: **Identity** migrates the user store and model only (`AddIdentityCore()`), never the cookie schemes or the Framework login controllers and `SignInManager` sign-in calls; **OpenID Connect** leaves the challenge, the callback and the session cookie on the Framework host. The remaining table routes — OAuth/JWT, federated token exchange, Negotiate and Membership — are fully unchanged, since they concern bearer tokens, the user store or access rules rather than the browser cookie. The gate is not limited to this table: `migrating-owin-to-aspnet-core` is reached from the OWIN pipeline work rather than from a signal here, and the same rule applies to it — its pipeline conversion is fine, its cookie and external-sign-in conversions are not. ### Step 2: Migrate Authentication Configuration #### Step 2A: Forms Authentication → Cookie Authentication Replace Forms Authentication with ASP.NET Core cookie authentication. Register the service in `Program.cs`: ```csharp // Old: web.config // <authentication mode="Forms"> // <forms loginUrl="~/Account/Login" timeout="30" slidingExpiration="true" /> // </authentication> // New: Program.cs builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme) .AddCookie(options => { options.LoginPath = "/Account/Login"; options.LogoutPath = "/Account/Logout"; options.AccessDeniedPath = "/Account/AccessDenied"; options.ExpireTimeSpan = TimeSpan.FromMinutes(30); options.SlidingExpiration = true; }); ``` Add authentication middleware in the correct order: ```csharp app.UseAuthentication(); app.UseAuthorization(); ``` **Security note:** In a full cutover, old Forms Authentication cookie tickets are not compatible with ASP.NET Core cookies, so users are logged out unless a separate transition is implemented. Do not apply that session-reset assumption to a side-by-side migration under either interop mechanism: under **Shared Cookie (Data Protection interop)** use `sharing-authentication-cookies-katana-interop` to rewrite legacy cookies instead, and under **Remote Authentication** the Core host is not issuing its own cookie at all, so the reset does not apply there either. **⚠️ machineKey migration:** `<machineKey>` in web.config is replaced by the Data Protection API. Key management is completely different. If the old app shared machine keys across servers for cookie decryption, configure Data Protection with a shared key ring: ```csharp builder.Services.AddDataProtection() .PersistKeysToFileSystem(new DirectoryInfo(@"\\server\share\keys")) .ProtectKeysWithCertificate(keyEncryptionCertificate) .SetApplicationName("SharedAppName"); ``` Use a certificate, Key Vault, or a shared DPAPI-NG descriptor for at-rest protection. Default per-machine/per-user DPAPI cannot protect a ring consumed by different hosts. #### Step 2B: Windows Authentication → Negotiate Authentication Replace web.config Windows auth with the Negotiate authentication handler: ```csharp // Old: web.config // <authentication mode="Windows" /> // New: Program.cs builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme) .AddNegotiate(); builder.Services.AddAuthorization(options => { options.FallbackPolicy = options.DefaultPolicy; }); ``` Add the NuGet package `Microsoft.AspNetCore.Authentication.Negotiate`. **Hosting differences:** Windows Authentication setup varies by host: - **IIS (in-process):** Enable Windows Authentication in IIS site settings; no code changes beyond the service registration. - **Kestrel:** Requires Negotiate handler configuration and may need SPN registration for domain environments. `WindowsIdentity` is still accessible via `HttpContext.User.Identity as WindowsIdentity`, but access paths through `Thread.CurrentPrincipal` or `ClaimsPrincipal.Current` no longer work. ### Step 3: Migrate Sign-In and Sign-Out Calls Replace `FormsAuthentication` static method calls with `HttpContext` extension methods. All ASP.NET Core equivalents are async. ```csharp // OLD: FormsAuthentication.SetAuthCookie(username, isPersistent); // NEW: var claims = new List<Claim> { new Claim(ClaimTypes.Name, username) }; var identity = new ClaimsIdentity(claims, CookieAuthenticationDefaults.AuthenticationScheme); var principal = new ClaimsPrincipal(identity); await HttpContext.SignInAsync( CookieAuthenticationDefaults.AuthenticationScheme, principal, new AuthenticationProperties { IsPersistent = isPersistent }); ``` ```csharp // OLD: FormsAuthentication.SignOut(); // NEW: await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme); ``` ```csharp // OLD: FormsAuthentication.RedirectToLoginPage(); // NEW (in a controller): return Challenge(); // Or explicit redirect: return Redirect("/Account/Login"); ``` **⚠️ Async requirement:** All sign-in/sign-out calls are async in ASP.NET Core. Update controller action signatures to return `Task<IActionResult>`. Replace `FormsAuthenticationTicket` custom data with additional claims on the `ClaimsIdentity`. Do not attempt to replicate the ticket format. ### Step 4: Migrate Membership and User Stores When Step 1 finds `SqlMembershipProvider`, `SimpleMembership`, a custom `MembershipProvider`, or `Roles` usage, read [Membership and user stores](ref/membership.md) before migrating them. Legacy password verification must match the old provider's exact hash algorithm, salt and encoding, then rehash on successful login. Under the side-by-side gate, migrate the user store with `AddIdentityCore()`, not cookie-issuing `AddIdentity()`; keep identity endpoints on the Framework host. ### Step 5: Migrate Authorization Rules #### Web.config Authorization → Policy-Based Authorization Replace `<authorization>` rules in web.config with ASP.NET Core authorization policies: ```xml <!-- Old: web.config --> <authorization> <allow roles="Admin,Manager" /> <deny users="*" /> </authorization> ``` ```csharp // New: Program.cs builder.Services.AddAuthorization(options => { options.FallbackPolicy = new AuthorizationPolicyBuilder() .RequireAuthenticatedUser() .Build(); }); ``` #### Authorize Attribute Changes For custom `AuthorizeAttribute` subclasses overriding `AuthorizeCore`, `OnAuthorization`, or `HandleUnauthorizedRequest`, use `migrating-mvc-filters` before replacing the attribute with a policy. It preserves inherited controller gates, TempData redirects, warning headers and explicit challenge behavior; the ordinary attribute mappings below do not migrate those side effects. `[Authorize(Roles = "Admin")]` works in both frameworks but resolves roles from different sources. Preserve each `ClaimsIdentity.RoleClaimType` and its role values when creating or transforming identities. Cookie `ClaimsIssuer` sets an issuer, not the role claim type; adding another cookie scheme does not repair the mapping and can break side-by-side identity. Use the claims inventory and policy example in `migrating-mvc-filters` to verify the existing principal instead. **`[Authorize(Users = "...")]` is removed** in ASP.NET Core. Replace with a policy: ```csharp // Old: [Authorize(Users = "admin,john")] // New: builder.Services.AddAuthorization(options => { options.AddPolicy("SpecificUsers", policy => policy.RequireAssertion(context => new[] { "admin", "john" }.Contains( context.User.Identity?.Name, StringComparer.OrdinalIgnoreCase))); }); // On the controller or action: [Authorize(Policy = "SpecificUsers")] ``` #### ClaimsPrincipal.Current Removal `ClaimsPrincipal.Current` and `Thread.CurrentPrincipal` do not work in ASP.NET Core. Replace all usages: ```csharp // Old (anywhere in code): var user = ClaimsPrincipal.Current; // New (in controllers): var user = HttpContext.User; // Or User property directly: var user = User; // New (in services — inject IHttpContextAccessor): public class MyService { private readonly IHttpContextAccessor _httpContextAccessor; public MyService(IHttpContextAccessor httpContextAccessor) { _httpContextAccessor = httpContextAccessor; } public ClaimsPrincipal GetCurrentUser() => _httpContextAccessor.HttpContext?.User; } ``` Register the accessor: ```csharp builder.Services.AddHttpContextAccessor(); ``` **⚠️ Security note:** `IHttpContextAccessor` returns null outside an HTTP request context (e.g., background tasks). Guard against null to avoid security bypass. ### Step 6: Migrate Anti-Forgery Tokens