Administration - Forms authentication

✖
Copy to clipboard

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 by default uses the following configuration:

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.

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:

Example - clear browsing data on sign-out


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.

Setting

Default value

Description

RequiredLength

8

The minimum length of the password string.

RequiredUniqueChars

1

The number of unique characters the password must contain

RequireDigit

true

Indicates if a digit is required as part of the password string.

RequireLowercase

true

Indicates if the password string must contain at least one lowercase letter.

RequireNonAlphanumeric

true

Indicates if the password string must contain at least one special character.

RequireUppercase

true

Indicates if the password string must contain at least one uppercase letter.

Configuration examples

Password options for the admin UI are stored in the AdminIdentityOptions class. You can change the default configuration by overriding desired options using the options pattern. For example:

Program.cs


using Kentico.Membership;

...

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

...

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

Email options

Email options configure emails related to user management sent by the Xperience application.

LinkExpiration

Default value: TimeSpan.FromDays(1)

The validity interval of account management-related URLs generated by the system (registration, password reset).

SenderAddress

Default value: no-reply

Sets the ‘From’ email address used by the system when sending user invitation and password reset emails. If only the address part is set, the domain is taken from SystemEmailOptions.SendingDomain.

RegistrationEmailMessageProvider

Default value: null

A delegate used when sending invitation emails to new users. Can be set to override the default message sent when inviting new users via the Users application.

The delegate is invoked with the IdentityEmailMessageProviderParameters object that contains following properties:

  • User – an object of the AdminApplicationUser type. Contains information about the user being invited that can be used to personalize the invitation message. Note that when sending invitation emails, only the user’s email property (and certain functional properties such as GUID and ID) is populated. The rest of the information can be optionally provided by the invited user after registration.
  • Link – a string holding a URL that allows the invited user to finish their registration into the system. Expires after the set LinkExpiration period has elapsed.
  • OriginalMessage – the default email message sent by the system.

    • The email is sent from the specified SenderAddress and contains the following wording:

      Subject: You’ve been invited to join {domain}

      Hi, you’ve been invited to join {domain}.

      Click the following URL to finish your registration: Click here

The delegate must return an EmailMessage object with at minimum the following properties populated:

  • From – the email address of the sender.
  • Recipients – the email address of the recipient. Can be accessed via User.Email.
  • Subject – the email subject.
  • Body – the email body. The body must contain the registration link (provided by the Link property). Otherwise, the invited user will be unable to complete the registration process.

See the following snippet for an example of the customization:

You can add other contextual information that you may want to include in the message using custom code. This example uses dependency injection to get an instance of IHttpContextAccessor and obtain the application domain. Use a similar approach to include, e.g., the request’s IP address.

Example - registration email customization


using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Options;

using Kentico.Membership;

// Use post-configure when you need to resolve dependencies from the IoC container
// (at this point already built and ready to resolve added services)
public class AdminIdentityOptionsConfiguration : IPostConfigureOptions<AdminIdentityOptions>
{
    private readonly IHttpContextAccessor httpContextAccessor;

    public AdminIdentityOptionsConfiguration(IHttpContextAccessor httpContextAccessor)
    {
        this.httpContextAccessor = httpContextAccessor;
    }

    public void PostConfigure(string name, AdminIdentityOptions options)
    {
        options.EmailOptions.SenderAddress = "notifications";
        options.EmailOptions.RegistrationEmailMessageProvider = providerParameters =>
        {
            providerParameters.OriginalMessage.Subject = 
                $"You have been invited to join {httpContextAccessor.HttpContext.Request.Host}";
            providerParameters.OriginalMessage.Body = 
                $"To finish you registration, visit: {providerParameters.Link}";

            return providerParameters.OriginalMessage;
        };
    }
}
Program.cs


...

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

...

// Ensures the options are set during post-configration
builder.Services.ConfigureOptions<AdminIdentityOptionsConfiguration>();

ResetPasswordEmailMessageProvider

Default value: null

A delegate used when sending password reset emails to users. Can be replaced to provide a version of the email message and metadata (sender email, subject, body, etc.) suitable for your project.

The delegate is invoked with the IdentityEmailMessageProviderParameters object that contains following properties:

  • User – an object of the AdminApplicationUser type. Contains information about the user requesting a password reset. This property can be used to personalize the message.
  • Link – a string holding a URL that allows the user to reset their password. Expires after the set LinkExpiration period has elapsed.
  • OriginalMessage – the default email message sent by the system.

    • The email is sent from the specified SenderAddress and contains the following wording:

      Subject: Password reset request from {domain}

      Hi {user.FirstName},

      you’ve requested a password reset for your account.

      You can set up a new password by visiting the following link: Click here to reset your password

The delegate must return an EmailMessage object with at minimum the following properties populated:

  • From – the email address of the sender.
  • Recipients – the email address of the recipient. Can be accessed via User.Email.
  • Subject – the email subject.
  • Body – the email body. The body must contain the password reset link (provided by the Link property). Otherwise, the user will be unable to reset their password.

See the following snippet for an example of the customization:

You can add other contextual information that you may want to include in the message using custom code. This example uses dependency injection to get an instance of IHttpContextAccessor and obtain the application domain. Use a similar approach to include, e.g., the request’s IP address.

Example - password reset email customization


using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Options;

using CMS.EmailEngine;

using Kentico.Membership;

// Use post-configure when you need to resolve dependencies from the container 
// (at this point already built and ready to resolve added services) 
public class AdminIdentityOptionsConfiguration : IPostConfigureOptions<AdminIdentityOptions>
{
    private readonly IHttpContextAccessor httpContextAccessor;

    public AdminIdentityOptionsConfiguration(IHttpContextAccessor httpContextAccessor)
    {
        this.httpContextAccessor = httpContextAccessor;
    }

    public void PostConfigure(string name, AdminIdentityOptions options)
    {
        options.EmailOptions.SenderAddress = "notifications";
        options.EmailOptions.ResetPasswordEmailMessageProvider = providerParameters =>
        {
            providerParameters.OriginalMessage.Subject =
                $"Password reset request from {httpContextAccessor.HttpContext.Request.Host}";
            providerParameters.OriginalMessage.Body =
                $"Hi {providerParameters.User.FirstName}, to reset your password, visit: {providerParameters.Link}";

            return providerParameters.OriginalMessage;
        };
    }
}
Program.cs


...

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

...

// Ensures the options are set during post-configration
builder.Services.ConfigureOptions<AdminIdentityOptionsConfiguration>();