Administration - Forms authentication

Xperience admin UI uses ASP.NET Core Identity to manage administration user accounts. The authentication pipeline for the admin UI is not shared with the live site and is configured independently via Kentico.Membership.AdminIdentityOptions.

The system provides the following configuration options. The default values are described in each section.

• Authentication options
  • Mode
  • ExpireTimespan
  • MultiFactorAuthenticationOptions
  • CookieEventsOptions
• Password options
  • Forbidden passwords
  • Configuration example
• Lockout options
• Email options
  • LinkExpiration
• Customize user management notifications

Authentication options

Authentication options configure the behavior of the system for admin UI authentication.

Mode

Default value: AdminAuthenticationMode.PrioritizeExternal

Allows you to configure if the default forms authentication should be maintained when an external authentication provider is registered for authentication into the Xperience admin UI. By default, when an external authentication provider is registered, this provider is the only authentication option. See Administration external authentication – Sign-in page behavior for more information.

ExpireTimespan

DefaultValue: 30 minutes

Sets the expiration time for admin UI authentication cookies. Uses sliding expiration by default.

MultiFactorAuthenticationOptions

Allows you to set up multi-factor authentication (MFA) for the administration. The underlying AdminMultiFactorAuthenticationOptions type provides the following properties:

• Enabled – set a true value to enable MFA for all administration users (there is no option for users to individually opt-in or out). This MFA feature only applies to the administration’s built-in forms authentication (external authentication providers have their own MFA features and configuration).
• ApplicationName – an identifier of your Xperience application displayed in MFA authenticator apps. The application name is passed to authenticator apps when users set up MFA using the displayed QR code. The default value is “Xperience by Kentico”.

builder.Services.Configure<AdminIdentityOptions>(options =>
{
    options.AuthenticationOptions.MultiFactorAuthenticationOptions.Enabled = true;
});

You can also adjust the email message sent when a user’s multi-factor authentication secret key is reset. See the Customize user management notifications section.

CookieEventsOptions

Contains events invoked when users sign in or out of the admin UI. Events fire for both the default forms authentication and external authentication.

The following events are available:

• OnSigningIn – called when users successfully sign in to the admin UI.
• OnSigningOut – called when users sign out of the admin UI.

Both events expose a context that allows you to modify the server response. For example:

builder.Services.Configure<AdminIdentityOptions>(options =>
{
    options.AuthenticationOptions.CookieEventsOptions.OnSigningOut = ctx =>
    {
        ctx.Response.Headers.Add("Clear-Site-Data", "*");
        return Task.CompletedTask;
    };
});

Password options

Password options configure the application’s password policy.

Forbidden passwords

Additionally, you can configure a list of forbidden passwords via the ForbiddenPasswords option. This allows you to stop users from choosing common or easy-to-guess passwords. By default, the list of forbidden passwords is empty.

The system first validates that new passwords fulfill the password policy requirements, and then checks against the forbidden password list. Forbidden passwords are case-insensitive, but otherwise must exactly match the entered text. Password variants with special characters or numbers must be added as separate forbidden passwords.

For example, “password” blocks passwords like “password”, “Password” or “passWord”, but not “p4ssword”, “passw0rd” or “password!”.

Configuration example

Password options for the admin UI are stored in the AdminIdentityOptions class, and can be accessed via the PasswordOptions property. You can change the default configuration by overriding desired options using the options pattern. For example:

using Kentico.Membership;

// ...

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

// ...

builder.Services.Configure<AdminIdentityOptions>(options =>
{
    options.PasswordOptions.RequireDigit = true;
    options.PasswordOptions.RequireLowercase = true;
    // ...

    // Adds a list of forbidden common passwords
    var forbiddenPasswords = new HashSet<string>()
    {
        "qwertyuiop1!",
        "password1!",
        "football1!"
    };
    options.PasswordOptions.ForbiddenPasswords = forbiddenPasswords;
});

Lockout options

Allows you to configure if and how the system locks administration user accounts after consecutive failed sign-ins. The underlying AdminLockoutOptions type provides the following properties:

• Enabled – true by default. Set a false value if you wish to fully disable the lockout functionality for the administration (not recommended).
• MaxFailedAccessAttempts – sets the number of consecutive failed sign-in attempts after which user accounts are locked. The default values is 5. The failed sign-in count is reset for a user whenever they sign in successfully.
• DefaultLockoutTimeSpan – a TimeSpan value that sets the lockout duration. The default value is 5 minutes. Users can also unlock their account immediately by clicking a link in a notification email, which is automatically sent when the account is locked.

using Kentico.Membership;

// ...

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.Configure<AdminIdentityOptions>(options =>
{
    // Configures account lockout for administration users

    // Allows 2 consecutive failed authentication attempts. Locks accounts after 3 failed authentications.
    options.LockoutOptions.MaxFailedAccessAttempts = 3;
    // Sets the lockout duration to 30 minutes
    options.LockoutOptions.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(30.0);
});

Email options

Email options configure emails related to user management sent by the Xperience application. You can customize these user management emails by editing the corresponding notifications in the Notifications application.

LinkExpiration

Currently, LinkExpiration is the only property configurable via the email options. This sets the validity interval of account management-related URLs generated by the system (registration, password reset, MFA secret key reset).

The default value is 1 day (TimeSpan.FromDays(1)).

builder.Services.Configure<AdminIdentityOptions>(options =>
{
    // Sets the validity of user management URLs to 2 days
    options.EmailOptions.LinkExpiration = TimeSpan.FromDays(2);
    ...
});

Customize user management notifications

The Notifications application within the Xperience administration contains a set of preconfigured notifications that inform users about events related to their account:

• User invitation
• User password reset
• Multi-factor authentication reset
• User account unlock

You can adjust the subject, sender address and content of these email to better fit your needs.