User Logon and Authentication

• Dec 28, 2023
• 4 minutes to read

The Security System supports the following authentication techniques:

• Windows Active Directory authentication
• Standard authentication
• OAuth2 and custom authentication

When you create a new XAF application, select an appropriate authentication type on the Choose Security page:

To enable authentication in an existing application, refer to the following sections:

• Enable Active Directory Authentication
• Enable Standard Authentication

Windows Active Directory Authentication

With Active Directory Authentication, Windows checks the user identity, and XAF does not store user passwords in the database. The user name is obtained from the WindowsIdentity object and includes the computer or domain name (for example, COMPUTERNAME\UserName or DOMAINNAME\UserName). You can enable the AuthenticationActiveDirectory.CreateUserAutomatically option to create a new user object automatically when a user logs in to the application for the first time.

For testing purposes, the Security System creates a new user object for your Windows account and assigns the administrative role to it when you start the application for the first time in DEBUG mode with the CreateUserAutomatically option enabled. In production code, the Security System does not create a new role or assign a role to a newly created user. In this case, you can assign a role manually in the Administrative UI or in the database directly, or specify the SecurityStrategyComplex.NewUserRoleName property. For further customization, you can handle the AuthenticationActiveDirectory.CustomCreateUser event (for example, you can automatically create restricted accounts associated with a specific default role).

Enable Active Directory Authentication

WinForms or ASP.NET Web Forms + .NET Framework

Invoke the Application Designer and drop the SecurityStrategyComplex and AuthenticationActiveDirectory components from the Visual Studio Toolbox to the designer’s Security pane:

WinForms (2-Tier Security) or ASP.NET Core Blazor + .NET 6

Files: ASP.NET Core Blazor - MySolution.Blazor.Server\Startup.cs WinForms - MySolution.Win\Startup.cs

C#

// ...
builder.Security
    .UseIntegratedMode(options => {
        // ...
        // Assign a role with the 'Default' name to new users.
        options.NewUserRoleName = "Default";
        // ...
    })
    .AddWindowsAuthentication(options => {
        // Enable auto-creation of new users.
        options.CreateUserAutomatically();
        // Customize new user auto-creation.
        options.Events.CustomCreateUser = (e) => {
            // ...
        };
    });
// ...

WinForms (Middle-Tier Security) or Web API + .NET 6+

Files: Middle Tier Server - MySolution.MiddleTier\Startup.cs Web API Service - MySolution.WebApi\Startup.cs

C#

// ...
services.AddXafAspNetCoreSecurity(Configuration, options => {
    // Assign a role with the 'Default' name to new users.
    options.NewUserRoleName = "Default";
    })
    .AddAuthenticationActiveDirectory(options => {
        // Enable auto-creation of new users.
        options.CreateUserAutomatically = true;
        // Customize new user auto-creation.
        options.Events.CustomCreateUser = (e) => {
            // ...
        };
    });
// ...

Standard Authentication

With Standard Authentication, the Security System uses the internal XAF authentication mechanism and stores user credentials in the application’s database. Users need to input their name and password in the login form before application startup.

Note

You can customize the authentication process and add extra logon parameters. The following help section describes how to do this: Customize Standard Authentication Behavior and Supply Additional Logon Parameters (Blazor).

For testing purposes, XAF generates the administrative and non-administrative user objects (Admin and User) with empty passwords. In production code, create users and assign roles to them in the Administrative UI or database directly.

Tip

To protect your applications from brute force attacks, XAF includes user lockout functionality. For more information, refer to the following topic: ISecurityUserLockout.

Enable Standard Authentication

WinForms or ASP.NET Web Forms + .NET Framework

Invoke the Application Designer and drop the SecurityStrategyComplex and AuthenticationActiveDirectory components from the Visual Studio Toolbox to the designer’s Security pane.

WinForms (2-Tier Security) or ASP.NET Core Blazor + .NET 6

Files: ASP.NET Core Blazor - MySolution.Blazor.Server\Startup.cs WinForms - MySolution.Win\Startup.cs

C#

// ...
builder.Security
    .UseIntegratedMode(options => {
        // ...
    })
    .AddPasswordAuthentication(options => {
        options.IsSupportChangePassword = true;
        // ...
    });
// ...

WinForms (Middle-Tier Security) or Web API + .NET 6+

Files: Middle Tier Server - MySolution.MiddleTier\Startup.cs Web API Service - MySolution.WebApi\Startup.cs

C#

// ...
services.AddXafAspNetCoreSecurity(Configuration, options => {
        //...
    })
    .AddAuthenticationStandard(options => {
        options.IsSupportChangePassword = true;
    });
// ...

OAuth2 and Custom Authentication

The following examples demonstrate custom authentication implementations:

• Customize Standard Authentication Behavior and Supply Additional Logon Parameters (Blazor)
• Active Directory and OAuth2 Authentication Providers in ASP.NET Core Blazor Applications
• Active Directory and OAuth2 Authentication Providers in WinForms Applications
• OAuth2 Authentication Providers in ASP.NET Web Forms Applications