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 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:
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:
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 setLinkExpiration
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.
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;
};
}
}
...
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 setLinkExpiration
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.
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;
};
}
}
...
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
...
// Ensures the options are set during post-configration
builder.Services.ConfigureOptions<AdminIdentityOptionsConfiguration>();