aspnetcore/security/authentication/accconfirm.md
By Rick Anderson, Ponant, and Joe Audette
This tutorial shows how to build an ASP.NET Core app with email confirmation and password reset. This tutorial is not a beginning topic. You should be familiar with:
:::moniker range=">= aspnetcore-8.0"
For Blazor guidance, which adds to or supersedes the guidance in this article, see the following resources:
:::moniker-end
<!-- see Dropbox/wrk/Code/SendGridConsole/Program.cs -->:::moniker range=">= aspnetcore-6.0"
Run the following commands to create a web app with authentication.
dotnet new webapp -au Individual -o WebPWrecover
cd WebPWrecover
dotnet run
<a name="regsim"></a>
Run the app, select the Register link, and register a user. Once registered, you are redirected to the to /Identity/Account/RegisterConfirmation page which contains a link to simulate email confirmation:
Click here to confirm your account link.Hello [email protected]! link, which redirects to the /Identity/Account/Manage/PersonalData page.The Click here to confirm your account link is displayed because an IEmailSender has not been implemented and registered with the dependency injection container. See the RegisterConfirmation source.
In this tutorial, SendGrid is used to send email. A SendGrid account and key is needed to send email. We recommend using SendGrid or another email service to send email rather than SMTP. SMTP is difficult to secure and set up correctly.
The SendGrid account may require adding a Sender.
Create a class to fetch the secure email key. For this sample, create Services/AuthMessageSenderOptions.cs:
Set the SendGridKey with the secret-manager tool. For example:
dotnet user-secrets set SendGridKey <key>
Successfully saved SendGridKey to the secret store.
On Windows, Secret Manager stores keys/value pairs in a secrets.json file in the %APPDATA%/Microsoft/UserSecrets/<WebAppName-userSecretsId> directory.
The contents of the secrets.json file aren't encrypted. The following markup shows the secrets.json file. The SendGridKey value has been removed.
{
"SendGridKey": "<key removed>"
}
For more information, see the Options pattern and configuration.
This tutorial shows how to add email notifications through SendGrid, but other email providers can be used.
Install the SendGrid NuGet package:
From the Package Manager Console, enter the following command:
Install-Package SendGrid
From the console, enter the following command:
dotnet add package SendGrid
See Get Started with SendGrid for Free to register for a free SendGrid account.
To Implement IEmailSender, create Services/EmailSender.cs with code similar to the following:
Add the following code to the Program.cs file:
EmailSender as a transient service.AuthMessageSenderOptions configuration instance.Run the web app, and test the account confirmation and password recovery flow.
<a name="resend"></a>
Select the Resend email confirmation link on the Login page.
The default inactivity timeout is 14 days. The following code sets the inactivity timeout to 5 days:
The following code changes all data protection tokens timeout period to 3 hours:
The built in Identity user tokens (see AspNetCore/src/Identity/Extensions.Core/src/TokenOptions.cs )have a one day timeout.
The default token lifespan of the Identity user tokens is one day. This section shows how to change the email token lifespan.
Add a custom xref:Microsoft.AspNetCore.Identity.DataProtectorTokenProvider%601 and xref:Microsoft.AspNetCore.Identity.DataProtectionTokenProviderOptions:
Add the custom provider to the service container:
<a name="debug"></a>
If you can't get email working:
EmailSender.Execute to verify SendGridClient.SendEmailAsync is called.EmailSender.Execute.A security best practice is to not use production secrets in test and development. If you publish the app to Azure, set the SendGrid secrets as application settings in the Azure Web App portal. The configuration system is set up to read keys from environment variables.
To complete this section, you must first enable an external authentication provider. See Facebook, Google, and external provider authentication.
You can combine local and social accounts by clicking on your email link. In the following sequence, "[email protected]" is first created as a local login; however, you can create the account as a social login first, then add a local login.
Click on the Manage link. Note the 0 external (social logins) associated with this account.
Click the link to another login service and accept the app requests. In the following image, Facebook is the external authentication provider:
The two accounts have been combined. You are able to sign in with either account. You might want your users to add local accounts in case their social login authentication service is down, or more likely they've lost access to their social account.
Enabling account confirmation on a site with users locks out all the existing users. Existing users are locked out because their accounts aren't confirmed. To work around existing user lockout, use one of the following approaches:
:::moniker-end
:::moniker range="< aspnetcore-6.0"
Run the following commands to create a web app with authentication.
dotnet new webapp -au Individual -uld -o WebPWrecover
cd WebPWrecover
dotnet run
Run the app, select the Register link, and register a user. Once registered, you are redirected to the to /Identity/Account/RegisterConfirmation page which contains a link to simulate email confirmation:
Click here to confirm your account link.Hello [email protected]! link, which redirects you to the /Identity/Account/Manage/PersonalData page.In this tutorial, SendGrid is used to send email. You can use other email providers. We recommend you use SendGrid or another email service to send email. SMTP is difficult to configure so mail is not marked as spam.
The SendGrid account may require adding a Sender.
Create a class to fetch the secure email key. For this sample, create Services/AuthMessageSenderOptions.cs:
Set the SendGridKey with the secret-manager tool. For example:
dotnet user-secrets set SendGridKey <SG.key>
Successfully saved SendGridKey = SG.keyVal to the secret store.
On Windows, Secret Manager stores keys/value pairs in a secrets.json file in the %APPDATA%/Microsoft/UserSecrets/<WebAppName-userSecretsId> directory.
The contents of the secrets.json file aren't encrypted. The following markup shows the secrets.json file. The SendGridKey value has been removed.
{
"SendGridKey": "<key removed>"
}
For more information, see the Options pattern and configuration.
This tutorial shows how to add email notifications through SendGrid, but you can send email using SMTP and other mechanisms.
Install the SendGrid NuGet package:
From the Package Manager Console, enter the following command:
Install-Package SendGrid
From the console, enter the following command:
dotnet add package SendGrid
See Get Started with SendGrid for Free to register for a free SendGrid account.
To Implement IEmailSender, create Services/EmailSender.cs with code similar to the following:
Add the following code to the ConfigureServices method in the Startup.cs file:
EmailSender as a transient service.AuthMessageSenderOptions configuration instance.Follow the instructions for Scaffold Identity and scaffold Account\RegisterConfirmation.
Run the web app, and test the account confirmation and password recovery flow.
<a name="resend"></a>
In .NET 5 or later, select the Resend email confirmation link on the Login page.
The default inactivity timeout is 14 days. The following code sets the inactivity timeout to 5 days:
The following code changes all data protection tokens timeout period to 3 hours:
The built in Identity user tokens (see AspNetCore/src/Identity/Extensions.Core/src/TokenOptions.cs )have a one day timeout.
The default token lifespan of the Identity user tokens is one day. This section shows how to change the email token lifespan.
Add a custom xref:Microsoft.AspNetCore.Identity.DataProtectorTokenProvider%601 and xref:Microsoft.AspNetCore.Identity.DataProtectionTokenProviderOptions:
Add the custom provider to the service container:
<a name="debug"></a>
If you can't get email working:
EmailSender.Execute to verify SendGridClient.SendEmailAsync is called.EmailSender.Execute.A security best practice is to not use production secrets in test and development. If you publish the app to Azure, set the SendGrid secrets as application settings in the Azure Web App portal. The configuration system is set up to read keys from environment variables.
To complete this section, you must first enable an external authentication provider. See Facebook, Google, and external provider authentication.
You can combine local and social accounts by clicking on your email link. In the following sequence, "[email protected]" is first created as a local login; however, you can create the account as a social login first, then add a local login.
Click on the Manage link. Note the 0 external (social logins) associated with this account.
Click the link to another login service and accept the app requests. In the following image, Facebook is the external authentication provider:
The two accounts have been combined. You are able to sign in with either account. You might want your users to add local accounts in case their social login authentication service is down, or more likely they've lost access to their social account.
Enabling account confirmation on a site with users locks out all the existing users. Existing users are locked out because their accounts aren't confirmed. To work around existing user lockout, use one of the following approaches:
:::moniker-end