Configure ASP.NET Core Identity

ASP.NET Core Identity uses default configuration for settings such as password policy, lockout time, and cookie settings. These settings can be overridden in the app's Startup class.

Identity options

The IdentityOptions class represents the options that can be used to configure the Identity system.

Claims Identity

IdentityOptions.ClaimsIdentity specifies the ClaimsIdentityOptions with the properties shown in the table.

Property Description Default
RoleClaimType Gets or sets the claim type used for a role claim. ClaimTypes.Role
SecurityStampClaimType Gets or sets the claim type used for the security stamp claim. AspNet.Identity.SecurityStamp
UserIdClaimType Gets or sets the claim type used for the user identifier claim. ClaimTypes.NameIdentifier
UserNameClaimType Gets or sets the claim type used for the user name claim. ClaimTypes.Name

Lockout

Locks out the user for a period of time after a given number of failed access attempts (default: 5 minute lockout after 5 failed access attempts). A successful authentication resets the failed access attempts count and resets the clock.

The following example shows the default values:

services.AddIdentity<ApplicationUser, IdentityRole>(options =>
    {
        // Lockout settings
        options.Lockout.AllowedForNewUsers = true;
        options.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(5);
        options.Lockout.MaxFailedAccessAttempts = 5; 
    })
    .AddEntityFrameworkStores<ApplicationDbContext>()
    .AddDefaultTokenProviders();

Confirm that PasswordSignInAsync sets lockoutOnFailure to true:

var result = await _signInManager.PasswordSignInAsync(
                 Input.Email, Input.Password, Input.RememberMe, lockoutOnFailure: true);

IdentityOptions.Lockout specifies the LockoutOptions with the properties shown in the table.

Property Description Default
AllowedForNewUsers Determines if a new user can be locked out. true
DefaultLockoutTimeSpan The amount of time a user is locked out when a lockout occurs. 5 minutes
MaxFailedAccessAttempts The number of failed access attempts until a user is locked out, if lockout is enabled. 5

Password

By default, Identity requires that passwords contain an uppercase character, lowercase character, a digit, and a non-alphanumeric character. Passwords must be at least six characters long. PasswordOptions can be changed in Startup.ConfigureServices.

ASP.NET Core 2.0 added the RequiredUniqueChars property. Otherwise, the options are the same as ASP.NET Core 1.x.

services.AddIdentity<ApplicationUser, IdentityRole>(options =>
    {
        // Password settings
        options.Password.RequireDigit = true;
        options.Password.RequiredLength = 8;
        options.Password.RequiredUniqueChars = 2;
        options.Password.RequireLowercase = true;
        options.Password.RequireNonAlphanumeric = true;
        options.Password.RequireUppercase = true;
    })
    .AddEntityFrameworkStores<ApplicationDbContext>()
    .AddDefaultTokenProviders();

IdentityOptions.Password specifies the PasswordOptions with the properties shown in the table.

Property Description Default
RequireDigit Requires a number between 0-9 in the password. true
RequiredLength The minimum length of the password. 6
RequiredUniqueChars Only applies to ASP.NET Core 2.0 or later.

Requires the number of distinct characters in the password.
1
RequireLowercase Requires a lowercase character in the password. true
RequireNonAlphanumeric Requires a non-alphanumeric character in the password. true
RequireUppercase Requires an uppercase character in the password. true

Sign-in

services.AddIdentity<ApplicationUser, IdentityRole>(options =>
    {
        // Signin settings
        options.SignIn.RequireConfirmedEmail = true;
        options.SignIn.RequireConfirmedPhoneNumber = false;
    })
    .AddEntityFrameworkStores<ApplicationDbContext>()
    .AddDefaultTokenProviders();

IdentityOptions.SignIn specifies the SignInOptions with the properties shown in the table.

Property Description Default
RequireConfirmedEmail Requires a confirmed email to sign in. false
RequireConfirmedPhoneNumber Requires a confirmed phone number to sign in. false

Tokens

IdentityOptions.Tokens specifies the TokenOptions with the properties shown in the table.

Property Description
AuthenticatorTokenProvider Gets or sets the AuthenticatorTokenProvider used to validate two-factor sign-ins with an authenticator.
ChangeEmailTokenProvider Gets or sets the ChangeEmailTokenProvider used to generate tokens used in email change confirmation emails.
ChangePhoneNumberTokenProvider Gets or sets the ChangePhoneNumberTokenProvider used to generate tokens used when changing phone numbers.
EmailConfirmationTokenProvider Gets or sets the token provider used to generate tokens used in account confirmation emails.
PasswordResetTokenProvider Gets or sets the IUserTwoFactorTokenProvider used to generate tokens used in password reset emails.
ProviderMap Used to construct a User Token Provider with the key used as the provider's name.

User

services.AddIdentity<ApplicationUser, IdentityRole>(options =>
    {
        // User settings
        options.User.RequireUniqueEmail = true;
    })
    .AddEntityFrameworkStores<ApplicationDbContext>()
    .AddDefaultTokenProviders();

IdentityOptions.User specifies the UserOptions with the properties shown in the table.

Property Description Default
AllowedUserNameCharacters Allowed characters in the username. abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ
0123456789
-._@+
RequireUniqueEmail Requires each user to have a unique email. false

Configure the app's cookie in Startup.ConfigureServices:

services.ConfigureApplicationCookie(options =>
{
    options.AccessDeniedPath = "/Account/AccessDenied";
    options.Cookie.Name = "YourAppCookieName";
    options.Cookie.HttpOnly = true; 
    options.ExpireTimeSpan = TimeSpan.FromMinutes(60); 
    options.LoginPath = "/Account/Login";
    // ReturnUrlParameter requires `using Microsoft.AspNetCore.Authentication.Cookies;`
    options.ReturnUrlParameter = CookieAuthenticationDefaults.ReturnUrlParameter;
    options.SlidingExpiration = true;
});

CookieAuthenticationOptions has the following properties:

Property Description
AccessDeniedPath Informs the handler that it should change an outgoing 403 Forbidden status code into a 302 Redirect onto the given path.

The default value is /Account/AccessDenied.
AuthenticationScheme Only applies to ASP.NET Core 1.x.

The logical name for a particular authentication scheme.
AutomaticAuthenticate Only applies to ASP.NET Core 1.x.

When true, cookie authentication should run on every request and attempt to validate and reconstruct any serialized principal it created.
AutomaticChallenge Only applies to ASP.NET Core 1.x.

If true, the authentication middleware handles automatic challenges. If false, the authentication middleware only alters responses when explicitly indicated by the AuthenticationScheme.
ClaimsIssuer Gets or sets the issuer that should be used for any claims that are created (inherited from AuthenticationSchemeOptions).
Cookie.Domain The domain to associate the cookie with.
Cookie.Expiration Gets or sets the lifespan of the HTTP cookie (not the authentication cookie). This property is overridden by ExpireTimeSpan. It shouldn't be used in the context of CookieAuthentication.
Cookie.HttpOnly Indicates whether a cookie is accessible by client-side script.

The default value is true.
Cookie.Name The name of the cookie.

The default value is .AspNetCore.Cookies.
Cookie.Path The cookie path.
Cookie.SameSite The SameSite attribute of the cookie.

The default value is SameSiteMode.Lax.
Cookie.SecurePolicy The CookieSecurePolicy configuration.

The default value is CookieSecurePolicy.SameAsRequest.
CookieDomain Only applies to ASP.NET Core 1.x.

The domain name where the cookie is served.
CookieHttpOnly Only applies to ASP.NET Core 1.x.

A flag indicating if the cookie should be accessible only to servers.

The default value is true.
CookiePath Only applies to ASP.NET Core 1.x.

Used to isolate apps running on the same host name.
CookieSecure Only applies to ASP.NET Core 1.x.

A flag indicating if the cookie created should be limited to HTTPS (CookieSecurePolicy.Always), HTTP or HTTPS (CookieSecurePolicy.None), or the same protocol as the request (CookieSecurePolicy.SameAsRequest).

The default value is CookieSecurePolicy.SameAsRequest.
CookieManager The component used to get cookies from the request or set them on the response.
DataProtectionProvider If set, the provider used by the CookieAuthenticationHandler for data protection.
Description Only applies to ASP.NET Core 1.x.

Additional information about the authentication type which is made available to the app.
Events The handler calls methods on the provider which give the app control at certain points where processing is occurring.
EventsType If set, the service type to get the Events instance instead of the property (inherited from AuthenticationSchemeOptions).
ExpireTimeSpan Controls how much time the authentication ticket stored in the cookie remains valid from the point it's created.

The default value is 14 days.
LoginPath When a user is unauthorized, they're redirected to this path to login.

The default value is /Account/Login.
LogoutPath When a user is logged out, they're redirected to this path.

The default value is /Account/Logout.
ReturnUrlParameter Determines the name of the query string parameter which is appended by the middleware when a 401 Unauthorized status code is changed to a 302 Redirect onto the login path.

The default value is ReturnUrl.
SessionStore An optional container in which to store the identity across requests.
SlidingExpiration When true, a new cookie is issued with a new expiration time when the current cookie is more than halfway through the expiration window.

The default value is true.
TicketDataFormat The TicketDataFormat is used to protect and unprotect the identity and other properties which are stored in the cookie value.