Scaffold Identity in ASP.NET Core projects

By Rick Anderson

:::moniker range=">= aspnetcore-8.0"

Blazor Identity scaffolding

ASP.NET Core Identity scaffolding adds ASP.NET Core Identity to Blazor Web Apps and Blazor Server apps. After the scaffolder adds the Identity Razor components to the app, you can customize the components to suit your app's requirements.

Although the scaffolder generates the necessary C# code to scaffold Identity into the app, you must update the project's database with an Entity Framework (EF) Core database migration to complete the process. This article explains the steps required to migrate a database.

Inspect the changes after running the Identity scaffolder. We recommend using GitHub or another source control system that shows file changes with a revert changes feature.

Services are required when using two-factor authentication (2FA), account confirmation and password recovery, and other security features with Identity. Services or service stubs aren't generated when scaffolding Identity. Services to enable these features must be added manually.

Razor Pages and MVC Identity scaffolding

ASP.NET Core provides ASP.NET Core Identity as a Razor class library (RCL). Applications that include Identity can apply the scaffolder to selectively add the source code contained in the Identity RCL. You might want to generate source code so you can modify the code and change the behavior. For example, you could instruct the scaffolder to generate the code used in registration. Customized Identity code overrides the default implementation provided by the Identity RCL. To gain full control of the UI and not use the default RCL, see the Create full Identity UI source section.

Applications that do not include authentication can apply the scaffolder to add the RCL Identity package. You have the option of selecting Identity code to be generated.

Although the scaffolder generates most of the necessary code, you need to update your project to complete the process. This document explains the steps needed to complete an Identity scaffolding update.

We recommend using a source control system that shows file differences and allows you to back out of changes. Inspect the changes after running the Identity scaffolder.

Services are required when using Two Factor Authentication, Account confirmation and password recovery, and other security features with Identity. Services or service stubs aren't generated when scaffolding Identity. Services to enable these features must be added manually. For example, see Require Email Confirmation.

Typically, apps created with individual accounts should not create a new data context.

Scaffold Identity into a Blazor project

This section applies to Blazor Web Apps and Blazor Server apps.

Run the Identity scaffolder:

Visual Studio

• From Solution Explorer, right-click on the project > Add > New Scaffolded Item.
• From the left pane of the Add New Scaffolded Item dialog, select Identity. Select Blazor Identity in the center pane. Select the Add button.
• In the Add Blazor Identity dialog:
  • Select or add with the plus (+) button the database context class (DbContext class).
  • Select the database provider (Database provider), which defaults to SQL Server.
  • Select or add with the plus (+) button the user class (User class).
  • Select the Add button.

.NET CLI

To add the required NuGet packages and tools, execute the following .NET CLI commands in a command shell opened to the project's root folder.

Paste all of the following commands at the prompt (>) of the command shell. When you paste multiple commands, a warning appears stating that multiple commands will execute. Select the Paste anyway button.

When you paste multiple commands, all but the last one runs. Press <kbd>Enter</kbd> to run the last command.

The following commands assume that you're using a SQL Server database and the SQL Server Entity EF Core database provider package (Microsoft.EntityFrameworkCore.SqlServer). If you're using a different database, swap the EF Core database provider package. The following providers are supported by the scaffolding tool†:

• SQLServer: Microsoft.EntityFrameworkCore.SqlServer
• SQLite: Microsoft.EntityFrameworkCore.Sqlite
• Cosmos: Microsoft.EntityFrameworkCore.Cosmos
• Postgres: Npgsql.EntityFrameworkCore.PostgreSQL

†The SQL Server, SQLite, and Cosmos database provider packages are owned, maintained, and supported by Microsoft. The PostgreSQL database provider package is owned, maintained, and supported by The Npgsql Development Team (npgsql/efcore.pg Github repository)).

dotnet tool install --global dotnet-aspnet-codegenerator
dotnet tool install --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools

[!IMPORTANT] After the first five commands execute, make sure that you press <kbd>Enter</kbd> on the keyboard to execute the last command.

The preceding commands add:

• Command-line interface (CLI) tools for EF Core
• aspnet-codegenerator scaffolding tool
• Design time tools for EF Core
• The SQLite and SQL Server providers with the EF Core package as a dependency
• Microsoft.VisualStudio.Web.CodeGeneration.Design for scaffolding

Run the following command to list the Identity scaffolder options:

dotnet aspnet-codegenerator identity -h

In the project folder, run the Identity scaffolder with the options you want. To scaffold Identity with the default Identity UI and the minimum number of files, run the following command:

dotnet aspnet-codegenerator identity --useDefaultUI

The generated Identity database code requires EF Core Migrations. The following steps explain how to create and apply a migration to the database.

Visual Studio

Visual Studio Connected Services are used to add an EF Core migration and update the database.

In Solution Explorer, double-click Connected Services. In the SQL Server Express LocalDB area of Service Dependencies, select the ellipsis (...) followed by Add migration.

Give the migration a Migration name, such as CreateIdentitySchema, which is a name that describes the migration. Wait for the database context to load in the DbContext class names field, which may take a few seconds. Select Finish to create the migration.

Select the Close button after the operation finishes.

Select the ellipsis (...) again followed by the Update database command.

The Update database with the latest migration dialog opens. Wait for the DbContext class names field to update and for prior migrations to load, which may take a few seconds. Select the Finish button.

Select the Close button after the operation finishes.

The update database command executes the Up method migrations that haven't been applied in a migration code file created by the scaffolder. In this case, the command executes the Up method in the Migrations/{TIME STAMP}_{MIGRATION NAME}.cs file, which creates the Identity tables, constraints, and indexes. The {TIME STAMP} placeholder is a time stamp, and the {MIGRATION NAME} placeholder is the migration name.

.NET CLI

From the project's root folder, execute the following .NET CLI command to add a migration. The {MIGRATION NAME} placeholder is used to name the migration, such as CreateIdentitySchema. Any name can be used, but the convention is to use a name that describes the migration.

dotnet ef migrations add {MIGRATION NAME}

Example:

dotnet ef migrations add CreateIdentitySchema

After the preceding command completes, update the database with the update command.

dotnet ef database update

The update command executes the Up method migrations that haven't been applied in a migration code file created by the scaffolder. In this case, the command executes the Up method in the Migrations/{TIME STAMP}_{MIGRATION NAME}.cs file, which creates the Identity tables, constraints, and indexes. The {TIME STAMP} placeholder is a time stamp, and the {MIGRATION NAME} placeholder is the migration name.

Client-side Blazor apps (Standalone Blazor WebAssembly)

Client-side Blazor apps (Standalone Blazor WebAssembly) use their own Identity UI approaches and can't use ASP.NET Core Identity scaffolding.

For more information, see the Blazor Security and Identity articles.

<a name="RPNA"></a>

Scaffold Identity into a Razor project without existing authorization

[!INCLUDE]

[!INCLUDE]

<a name="efm"></a>

Migrations, UseAuthentication, and layout

[!INCLUDE]

<a name="useauthentication"></a>

Layout changes

Optional: Add the login partial (_LoginPartial) to the layout file:

[!code-cshtml]

Scaffold Identity into a Razor project with authorization

[!INCLUDE]

[!INCLUDE]

Scaffold Identity into an MVC project without existing authorization

[!INCLUDE]

[!INCLUDE]

Optional: Add the login partial (_LoginPartial) to the Views/Shared/_Layout.cshtml file:

[!code-cshtml]

[!INCLUDE]

Add MapRazorPages to Program.cs as shown in the following highlighted code:

[!code-csharp]

Scaffold Identity into an MVC project with authorization

[!INCLUDE]

[!INCLUDE]

<a name="full"></a>

Create full Identity UI source

To maintain full control of the Identity UI, run the Identity scaffolder and select Override all files.

Password configuration

If xref:Microsoft.AspNetCore.Identity.PasswordOptions are configured in Startup.ConfigureServices, [StringLength] attribute configuration might be required for the Password property in scaffolded Identity pages. InputModel Password properties are found in the following files:

• Areas/Identity/Pages/Account/Register.cshtml.cs
• Areas/Identity/Pages/Account/ResetPassword.cshtml.cs

Disable a page

This section shows how to disable the register page but the approach can be used to disable any page.

To disable user registration:

• Scaffold Identity. Include Account.Register, Account.Login, and Account.RegisterConfirmation. For example:

  dotnetcliCopy

   dotnet aspnet-codegenerator identity -dc RPauth.Data.ApplicationDbContext --files "Account.Register;Account.Login;Account.RegisterConfirmation"
  

• Update Areas/Identity/Pages/Account/Register.cshtml.cs so users can't register from this endpoint:

  [!code-csharp]

• Update Areas/Identity/Pages/Account/Register.cshtml to be consistent with the preceding changes:

  [!code-cshtml]

• Comment out or remove the registration link from Areas/Identity/Pages/Account/Login.cshtml

  cshtmlCopy

  @*
  <p>
      <a asp-page="./Register" asp-route-returnUrl="@Model.ReturnUrl">Register as a new user</a>
  </p>
  *@
  

• Update the Areas/Identity/Pages/Account/RegisterConfirmation page.

  • Remove the code and links from the cshtml file.
  • Remove the confirmation code from the PageModel:
  csharpCopy

   [AllowAnonymous]
    public class RegisterConfirmationModel : PageModel
    {
        public IActionResult OnGet()
        {  
            return Page();
        }
    }
  

Use another app to add users

Provide a mechanism to add users outside the web app. Options to add users include:

• A dedicated admin web app.
• A console app.

The following code outlines one approach to adding users:

• A list of users is read into memory.
• A strong unique password is generated for each user.
• The user is added to the Identity database.
• The user is notified and told to change the password.

[!code-csharp]

The following code outlines adding a user:

[!code-csharp]

A similar approach can be followed for production scenarios.

Prevent publish of static Identity assets

To prevent publishing static Identity assets to the web root, see xref:security/authentication/identity#prevent-publish-of-static-identity-assets.

:::moniker-end

:::moniker range=">= aspnetcore-6.0 < aspnetcore-8.0"

ASP.NET Core provides ASP.NET Core Identity as a Razor class library (RCL). Applications that include Identity can apply the scaffolder to selectively add the source code contained in the Identity RCL. You might want to generate source code so you can modify the code and change the behavior. For example, you could instruct the scaffolder to generate the code used in registration. Generated code takes precedence over the same code in the Identity RCL. To gain full control of the UI and not use the default RCL, see the section Create full Identity UI source.

Applications that do not include authentication can apply the scaffolder to add the RCL Identity package. You have the option of selecting Identity code to be generated.

Although the scaffolder generates most of the necessary code, you need to update your project to complete the process. This document explains the steps needed to complete an Identity scaffolding update.

We recommend using a source control system that shows file differences and allows you to back out of changes. Inspect the changes after running the Identity scaffolder.

Services are required when using Two Factor Authentication, Account confirmation and password recovery, and other security features with Identity. Services or service stubs aren't generated when scaffolding Identity. Services to enable these features must be added manually. For example, see Require Email Confirmation.

Typically, apps created with individual accounts should not create a new data context.

<a name="RPNA"></a>

Scaffold Identity into a Razor project without existing authorization

[!INCLUDE]

[!INCLUDE]

<a name="efm"></a>

Migrations, UseAuthentication, and layout

[!INCLUDE]

<a name="useauthentication"></a>

Layout changes

Optional: Add the login partial (_LoginPartial) to the layout file:

[!code-cshtml]

Scaffold Identity into a Razor project with authorization

[!INCLUDE]

[!INCLUDE]

Scaffold Identity into an MVC project without existing authorization

[!INCLUDE]

[!INCLUDE]

Optional: Add the login partial (_LoginPartial) to the Views/Shared/_Layout.cshtml file:

[!code-cshtml]

[!INCLUDE]

Add MapRazorPages to Program.cs as shown in the following highlighted code:

[!code-cshtml]

Scaffold Identity into an MVC project with authorization

[!INCLUDE]

[!INCLUDE]

Scaffold Identity into a server-side Blazor app with authorization

[!INCLUDE]

[!INCLUDE]

Migrations

[!INCLUDE]

Style authentication endpoints

Because server-side Blazor apps use Razor Pages Identity pages, the styling of the UI changes when a visitor navigates between Identity pages and components. You have two options to address the incongruous styles:

• Custom Identity components
• Use a custom layout with Blazor app styles

Custom Identity components

ASP.NET Core Identity is designed to work in the context of HTTP request and response communication, which isn't the primary client-server communication model in Blazor apps. ASP.NET Core apps that use ASP.NET Core Identity for user management should use Razor Pages instead of Razor components for Identity-related UI, such as user registration, login, logout, and other user management tasks.

Because xref:Microsoft.AspNetCore.Identity.SignInManager%601 and xref:Microsoft.AspNetCore.Identity.UserManager%601 aren't supported in Razor components, we recommend using web API to manage Identity actions from Razor components via a server-side Identity-enabled ASP.NET Core app. For guidance on creating web APIs for Blazor apps, see xref:blazor/call-web-api.

An approach to using Razor components for Identity instead of Razor pages is to build your own custom Identity Razor components, but Microsoft doesn't recommend or support the approach. For additional context, explore the following discussions. In the following discussions, code examples in issue comments and code examples cross-linked in non-Microsoft GitHub repositories aren't supported by Microsoft but might be helpful to some developers:

• Support Custom Login Component when using Identity (dotnet/aspnetcore #13601)
• Reiteration on the SigninManager<T> not being supported in Razor Components (dotnet/aspnetcore #34095)
• There is no info on how to actually implement custom login form for server-side blazor (dotnet/AspNetCore.Docs #16813)

For additional assistance when seeking to build custom Identity Razor components or searching for third-party Razor components, we recommend the following resources:

• Stack Overflow (tag: blazor) (Public support forum)
• ASP.NET Core Slack Team (Public support chat)
• Blazor Gitter (Public support chat)
• Awesome Blazor (Links to community-maintained Blazor resources)

Use a custom layout with Blazor app styles

The Identity pages layout and styles can be modified to produce pages that use styles similar to the default Blazor theme. This approach isn't covered by the documentation.

Client-side Blazor apps

Client-side Blazor apps use their own Identity UI approaches and can't use ASP.NET Core Identity scaffolding. Server-side ASP.NET Core apps of hosted Blazor solutions can follow the Razor Pages/MVC guidance in this article and are configured just like any other type of ASP.NET Core app that supports Identity.

The Blazor framework doesn't include Razor component versions of Identity UI pages. Identity UI Razor components can be custom built or obtained from unsupported third-party sources.

For more information, see the Blazor Security and Identity articles.

<a name="full"></a>

Create full Identity UI source

To maintain full control of the Identity UI, run the Identity scaffolder and select Override all files.

Password configuration

If xref:Microsoft.AspNetCore.Identity.PasswordOptions are configured in Startup.ConfigureServices, [StringLength] attribute configuration might be required for the Password property in scaffolded Identity pages. InputModel Password properties are found in the following files:

• Areas/Identity/Pages/Account/Register.cshtml.cs
• Areas/Identity/Pages/Account/ResetPassword.cshtml.cs

Disable a page

This section shows how to disable the register page but the approach can be used to disable any page.

To disable user registration:

• Scaffold Identity. Include Account.Register, Account.Login, and Account.RegisterConfirmation. For example:

  dotnetcliCopy

   dotnet aspnet-codegenerator identity -dc RPauth.Data.ApplicationDbContext --files "Account.Register;Account.Login;Account.RegisterConfirmation"
  

• Update Areas/Identity/Pages/Account/Register.cshtml.cs so users can't register from this endpoint:

  [!code-csharp]

• Update Areas/Identity/Pages/Account/Register.cshtml to be consistent with the preceding changes:

  [!code-cshtml]

• Comment out or remove the registration link from Areas/Identity/Pages/Account/Login.cshtml

  cshtmlCopy

  @*
  <p>
      <a asp-page="./Register" asp-route-returnUrl="@Model.ReturnUrl">Register as a new user</a>
  </p>
  *@
  

• Update the Areas/Identity/Pages/Account/RegisterConfirmation page.

  • Remove the code and links from the cshtml file.
  • Remove the confirmation code from the PageModel:
  csharpCopy

   [AllowAnonymous]
    public class RegisterConfirmationModel : PageModel
    {
        public IActionResult OnGet()
        {  
            return Page();
        }
    }
  

Use another app to add users

Provide a mechanism to add users outside the web app. Options to add users include:

• A dedicated admin web app.
• A console app.

The following code outlines one approach to adding users:

• A list of users is read into memory.
• A strong unique password is generated for each user.
• The user is added to the Identity database.
• The user is notified and told to change the password.

[!code-csharp]

The following code outlines adding a user:

[!code-csharp]

A similar approach can be followed for production scenarios.

Prevent publish of static Identity assets

To prevent publishing static Identity assets to the web root, see xref:security/authentication/identity#prevent-publish-of-static-identity-assets.

:::moniker-end

:::moniker range="< aspnetcore-6.0"

ASP.NET Core provides ASP.NET Core Identity as a Razor class library (RCL). Applications that include Identity can apply the scaffolder to selectively add the source code contained in the Identity RCL. You might want to generate source code so you can modify the code and change the behavior. For example, you could instruct the scaffolder to generate the code used in registration. Generated code takes precedence over the same code in the Identity RCL. To gain full control of the UI and not use the default RCL, see the section Create full Identity UI source.

Applications that do not include authentication can apply the scaffolder to add the RCL Identity package. You have the option of selecting Identity code to be generated.

Although the scaffolder generates most of the necessary code, you need to update your project to complete the process. This document explains the steps needed to complete an Identity scaffolding update.

We recommend using a source control system that shows file differences and allows you to back out of changes. Inspect the changes after running the Identity scaffolder.

Services are required when using Two Factor Authentication, Account confirmation and password recovery, and other security features with Identity. Services or service stubs aren't generated when scaffolding Identity. Services to enable these features must be added manually. For example, see Require Email Confirmation.

When scaffolding Identity with a new data context into a project with existing individual accounts, open Startup.ConfigureServices and remove the calls to:

• AddDbContext
• AddDefaultIdentity

For example, AddDbContext and AddDefaultIdentity are commented out in the following code:

[!code-csharp]

The preceding code comments out the code that is duplicated in Areas/Identity/IdentityHostingStartup.cs

Typically, apps created with individual accounts should not create a new data context.

Scaffold Identity into an empty project

[!INCLUDE]

Update the Startup class with code similar to the following:

[!code-csharp]

[!INCLUDE]

[!INCLUDE]

Scaffold Identity into a Razor project without existing authorization

[!INCLUDE]

Identity is configured in Areas/Identity/IdentityHostingStartup.cs. For more information, see IHostingStartup.

<a name="efm"></a>

Migrations, UseAuthentication, and layout

[!INCLUDE]

<a name="useauthentication"></a>

Enable authentication

Update the Startup class with code similar to the following:

[!code-csharp]

[!INCLUDE]

Layout changes

Optional: Add the login partial (_LoginPartial) to the layout file:

[!code-cshtml]

Scaffold Identity into a Razor project with authorization

[!INCLUDE]

Some Identity options are configured in Areas/Identity/IdentityHostingStartup.cs. For more information, see IHostingStartup.

Scaffold Identity into an MVC project without existing authorization

[!INCLUDE]

Optional: Add the login partial (_LoginPartial) to the Views/Shared/_Layout.cshtml file:

[!code-cshtml]

Move the Pages/Shared/_LoginPartial.cshtml file to Views/Shared/_LoginPartial.cshtml.

Identity is configured in Areas/Identity/IdentityHostingStartup.cs. For more information, see IHostingStartup.

[!INCLUDE]

Update the Startup class with code similar to the following:

[!code-csharp]

[!INCLUDE]

Scaffold Identity into an MVC project with authorization

[!INCLUDE]

Scaffold Identity into a server-side Blazor app without existing authorization

[!INCLUDE]

Identity is configured in Areas/Identity/IdentityHostingStartup.cs. For more information, see IHostingStartup.

Migrations

[!INCLUDE]

Style authentication endpoints

Because server-side Blazor apps use Razor Pages Identity pages, the styling of the UI changes when a visitor navigates between Identity pages and components. You have two options to address the incongruous styles:

• Custom Identity components
• Use a custom layout with Blazor app styles

Custom Identity components

An approach to using components for Identity instead of pages is to build Identity components. Because SignInManager and UserManager aren't supported in Razor components, use web API endpoints in the Blazor app to process user account actions.

Use a custom layout with Blazor app styles

The Identity pages layout and styles can be modified to produce pages that use styles similar to the default Blazor theme. This approach isn't covered by the documentation.

Scaffold Identity into a server-side Blazor app with authorization

[!INCLUDE]

Some Identity options are configured in Areas/Identity/IdentityHostingStartup.cs. For more information, see IHostingStartup.

Client-side Blazor apps

Client-side Blazor apps use their own Identity UI approaches and can't use ASP.NET Core Identity scaffolding. Server-side ASP.NET Core apps of hosted Blazor solutions can follow the Razor Pages/MVC guidance in this article and are configured just like any other type of ASP.NET Core app that supports Identity.

The Blazor framework doesn't include Razor component versions of Identity UI pages. Identity UI Razor components can be custom built or obtained from unsupported third-party sources.

For more information, see the Blazor Security and Identity articles.

<a name="full"></a>

Create full Identity UI source

To maintain full control of the Identity UI, run the Identity scaffolder and select Override all files.

The following highlighted code shows the changes to replace the default Identity UI with Identity in an ASP.NET Core 2.1 web app. You might want to do this to have full control of the Identity UI.

[!code-csharp]

The default Identity is replaced in the following code:

[!code-csharp]

The following code sets the xref:Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationOptions.LoginPath%2A, xref:Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationOptions.LogoutPath%2A, and xref:Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationOptions.AccessDeniedPath%2A):

[!code-csharp]

Register an IEmailSender implementation, for example:

[!code-csharp]

[!code-csharp]

Password configuration

If xref:Microsoft.AspNetCore.Identity.PasswordOptions are configured in Startup.ConfigureServices, [StringLength] attribute configuration might be required for the Password property in scaffolded Identity pages. InputModel Password properties are found in the following files:

• Areas/Identity/Pages/Account/Register.cshtml.cs
• Areas/Identity/Pages/Account/ResetPassword.cshtml.cs

Disable a page

This section shows how to disable the register page but the approach can be used to disable any page.

To disable user registration:

• Scaffold Identity. Include Account.Register, Account.Login, and Account.RegisterConfirmation. For example:

  dotnetcliCopy

   dotnet aspnet-codegenerator identity -dc RPauth.Data.ApplicationDbContext --files "Account.Register;Account.Login;Account.RegisterConfirmation"
  

• Update Areas/Identity/Pages/Account/Register.cshtml.cs so users can't register from this endpoint:

  [!code-csharp]

• Update Areas/Identity/Pages/Account/Register.cshtml to be consistent with the preceding changes:

  [!code-cshtml]

• Comment out or remove the registration link from Areas/Identity/Pages/Account/Login.cshtml

  cshtmlCopy

  @*
  <p>
      <a asp-page="./Register" asp-route-returnUrl="@Model.ReturnUrl">Register as a new user</a>
  </p>
  *@
  

• Update the Areas/Identity/Pages/Account/RegisterConfirmation page.

  • Remove the code and links from the cshtml file.
  • Remove the confirmation code from the PageModel:
  csharpCopy

   [AllowAnonymous]
    public class RegisterConfirmationModel : PageModel
    {
        public IActionResult OnGet()
        {  
            return Page();
        }
    }
  

Use another app to add users

Provide a mechanism to add users outside the web app. Options to add users include:

• A dedicated admin web app.
• A console app.

The following code outlines one approach to adding users:

• A list of users is read into memory.
• A strong unique password is generated for each user.
• The user is added to the Identity database.
• The user is notified and told to change the password.

[!code-csharp]

The following code outlines adding a user:

[!code-csharp]

A similar approach can be followed for production scenarios.

Prevent publish of static Identity assets

To prevent publishing static Identity assets to the web root, see xref:security/authentication/identity#prevent-publish-of-static-identity-assets.

Additional resources

Changes to authentication code to ASP.NET Core 2.1 or later

:::moniker-end