AspNetCore.Docs/aspnetcore/security/authentication/scaffold-identity.md

title	author	description	monikerRange	ms.author	ms.custom	ms.date	uid
Scaffold Identity in ASP.NET Core projects	rick-anderson	Learn how to scaffold Identity in an ASP.NET Core project.	>= aspnetcore-2.1	riande	mvc	10/24/2018	security/authentication/scaffold-identity

Scaffold Identity in ASP.NET Core projects

By Rick Anderson

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

ASP.NET Core provides ASP.NET Core Identity as a Razor Class Library. Applications that include Identity can apply the scaffolder to selectively add the source code contained in the Identity Razor Class Library (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.

This document contains more complete instructions than the ScaffoldingReadme.txt file which is generated when running the the scaffolder.

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.

Migrations, UseAuthentication, and layout

[!INCLUDE]

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-htmlMain]

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-htmlMain]

• 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]

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 LoginPath, LogoutPath, and AccessDeniedPath:

[!code-csharp]

Register an IEmailSender implementation, for example:

[!code-csharp]

[!code-csharp]

Disable register page

To disable user registration:

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

   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

@*
<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:

   [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.

Additional resources

• Changes to authentication code to ASP.NET Core 2.1 and later

::: moniker-end

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

ASP.NET Core 2.1 and later provides ASP.NET Core Identity as a Razor Class Library. Applications that include Identity can apply the scaffolder to selectively add the source code contained in the Identity Razor Class Library (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'll have to update your project to complete the process. This document explains the steps needed to complete an Identity scaffolding update.

When the Identity scaffolder is run, a ScaffoldingReadme.txt file is created in the project directory. The ScaffoldingReadme.txt file contains general instructions on what's needed to complete the Identity scaffolding update. This document contains more complete instructions than the ScaffoldingReadme.txt file.

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.

[!NOTE] 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.

Scaffold identity into an empty project

[!INCLUDE]

Add the following highlighted calls to the Startup class:

[!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.

Migrations, UseAuthentication, and layout

[!INCLUDE]

Enable authentication

In the Configure method of the Startup class, call UseAuthentication after UseStaticFiles:

[!code-csharp]

[!INCLUDE]

Layout changes

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

[!code-htmlMain]

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-html]

• 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]

Call UseAuthentication after UseStaticFiles:

[!code-csharp]

[!INCLUDE]

Scaffold identity into an MVC project with authorization

[!INCLUDE]

Delete the Pages/Shared folder and the files in that folder.

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 LoginPath, LogoutPath, and AccessDeniedPath:

[!code-csharp]

Register an IEmailSender implementation, for example:

[!code-csharp]

[!code-csharp]

Disable register page

To disable user registration:

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

   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

@*
<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:

   [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.

Additional resources

• Changes to authentication code to ASP.NET Core 2.1 and later

::: moniker-end