Windows-verificatie configureren in ASP.NET Core

Door Rick Anderson en Kirk Larkin

Windows-verificatie (ook wel onderhandelen, Kerberos of NTLM-verificatie genoemd) kan worden geconfigureerd voor ASP.NET Core-apps die worden gehost met IIS of KestrelHTTP.sys.

Windows-verificatie is afhankelijk van het besturingssysteem om gebruikers van ASP.NET Core-apps te verifiëren. Windows-verificatie wordt gebruikt voor servers die worden uitgevoerd op een bedrijfsnetwerk met behulp van Active Directory-domeinidentiteiten of Windows-accounts om gebruikers te identificeren. Windows-verificatie is het meest geschikt voor intranetomgevingen waar gebruikers, client-apps en webservers deel uitmaken van hetzelfde Windows-domein.

Opmerking

Windows-verificatie wordt niet ondersteund met HTTP/2. Authenticatie-uitdagingen kunnen worden verzonden op HTTP/2-antwoorden, maar de client moet terugschakelen naar HTTP/1.1 voordat deze authenticeert.

Scenario's voor proxy en load balancer

Windows-verificatie is een stateful scenario dat voornamelijk wordt gebruikt in een intranet, waarbij een proxy of load balancer meestal geen verkeer tussen clients en servers verwerkt. Als er een proxy of load balancer wordt gebruikt, functioneert Windows-verificatie alleen mits de proxy of load balancer:

• Verzorgt de authenticatie.
• Geeft de gebruikersverificatiegegevens door aan de app (bijvoorbeeld in een aanvraagheader), die op de verificatiegegevens reageert.

Een alternatief voor Windows-verificatie in omgevingen waarin proxy's en load balancers worden gebruikt, is Active Directory Federated Services (ADFS) met OpenID Connect (OIDC).

IIS/IIS Express

Voeg het Microsoft.AspNetCore.Authentication.Negotiate NuGet-pakket en de verificatieservices toe door in te bellenAddAuthentication:Program.cs

using Microsoft.AspNetCore.Authentication.Negotiate;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
   .AddNegotiate();

builder.Services.AddAuthorization(options =>
{
    options.FallbackPolicy = options.DefaultPolicy;
});
builder.Services.AddRazorPages();

var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

app.MapRazorPages();

app.Run();

De voorgaande code is gegenereerd door de sjabloon ASP.NET Basispagina's Razor met Windows-verificatie opgegeven.

Startinstellingen (debugger)

Configuratie voor startinstellingen is alleen van invloed op het Properties/launchSettings.json bestand voor IIS Express en configureert IIS niet voor Windows-verificatie. Serverconfiguratie wordt uitgelegd in de sectie IIS .

De webtoepassingssjablonen die beschikbaar zijn via Visual Studio of de .NET CLI, kunnen worden geconfigureerd ter ondersteuning van Windows-verificatie, waardoor het Properties/launchSettings.json bestand automatisch wordt bijgewerkt.

Visual Studio

Nieuw project

Maak een nieuwe Razor Pagina's- of MVC-app. Stel in het dialoogvenster Aanvullende informatie het verificatietype in op Windows.

Voer de app uit. De gebruikersnaam wordt weergegeven in de gebruikersinterface van de weergegeven app.

Bestaand project

De eigenschappen van het project schakelen Windows-verificatie in en schakel anonieme verificatie uit. Het dialoogvenster Startprofielen openen:

1. Klik in Solution Explorer met de rechtermuisknop op het project en selecteer Eigenschappen.
2. Selecteer het tabblad Foutopsporings > algemeen en selecteer de gebruikersinterface voor het openen van startprofielen voor foutopsporing.
3. Schakel het selectievakje voor Anonieme verificatie inschakelen uit.
4. Schakel het selectievakje in voor Windows-verificatie inschakelen.

U kunt de eigenschappen ook configureren in het iisSettings knooppunt van het launchSettings.json bestand:

"iisSettings": {
    "windowsAuthentication": true,
    "anonymousAuthentication": false,
    "iisExpress": {
        "applicationUrl": "http://localhost:52171/",
        "sslPort": 44308
    }
}

.NET CLI

Nieuw project

Voer de dotnet new opdracht uit met het webapp argument (ASP.NET Core Web App) en de --auth Windows schakel:

dotnet new webapp --auth Windows

Bestaand project

Werk het iisSettings knooppunt van het launchSettings.json bestand bij:

"iisSettings": {
    "windowsAuthentication": true,
    "anonymousAuthentication": false,
    "iisExpress": {
        "applicationUrl": "http://localhost:52171/",
        "sslPort": 44308
    }
}

IIS

IIS maakt gebruik van de ASP.NET Core-module voor het hosten van ASP.NET Core-apps. Windows-verificatie is geconfigureerd voor IIS via het web.config-bestand . In de volgende delen ziet u hoe:

• Geef een lokaal web.config-bestand op dat Windows-verificatie op de server activeert wanneer de app wordt geïmplementeerd.
• Gebruik IIS-beheer om het web.config-bestand te configureren van een ASP.NET Core-app die al op de server is geïmplementeerd.

Als u dit nog niet hebt gedaan, schakelt u IIS in om ASP.NET Core-apps te hosten. Zie Host ASP.NET Core in Windows met IIS voor meer informatie.

Schakel de IIS-functieservice in voor Windows-verificatie. Zie Windows-verificatie inschakelen in IIS-functieservices (zie stap 2) voor meer informatie.

IIS Integration Middleware is geconfigureerd voor het automatisch verifiëren van aanvragen. Zie Host ASP.NET Core in Windows met IIS: IIS-opties (AutomaticAuthentication) voor meer informatie.

De ASP.NET Core-module is geconfigureerd om het Windows-verificatietoken standaard door te sturen naar de app. Zie ASP.NET Core Module configuration reference: Attributes of the aspNetCore element (Kenmerken van het aspNetCore-element) voor meer informatie.

Gebruik een van de volgende methoden:

• Voordat u het project publiceert en implementeert, voegt u het volgende web.config bestand toe aan de hoofdmap van het project:

  <?xml version="1.0" encoding="utf-8"?>
  <configuration>
    <location path="." inheritInChildApplications="false">
      <system.webServer>
        <security>
          <authentication>
            <anonymousAuthentication enabled="false" />
            <windowsAuthentication enabled="true" />
          </authentication>
        </security>
      </system.webServer>
    </location>
  </configuration>
  

  Wanneer het project wordt gepubliceerd door de .NET Core SDK (zonder dat de <IsTransformWebConfigDisabled> eigenschap is ingesteld true in het projectbestand), bevat het gepubliceerde web.config-bestand de <location><system.webServer><security><authentication> sectie. Zie <IsTransformWebConfigDisabled> voor meer informatie over de eigenschap.

• Nadat u het project hebt gepubliceerd en geïmplementeerd, moet u de configuratie aan de serverzijde uitvoeren met IIS-beheer:

  1. Selecteer in IIS-beheer de IIS-site onder het knooppunt Sites van de zijbalk Verbindingen .
  2. Dubbelklik op Verificatie in het IIS-gebied .
  3. Selecteer Anonieme verificatie. Selecteer Uitschakelen in de zijbalk Acties .
  4. Selecteer Windows-verificatie. Selecteer Inschakelen in de zijbalk Acties .

  Wanneer deze acties worden uitgevoerd, wijzigt IIS Manager het web.config-bestand van de app. Er wordt een <system.webServer><security><authentication> knooppunt toegevoegd met bijgewerkte instellingen voor anonymousAuthentication en windowsAuthentication:

  <system.webServer>
    <security>
      <authentication>
        <anonymousAuthentication enabled="false" />
        <windowsAuthentication enabled="true" />
      </authentication>
    </security>
  </system.webServer>
  

  De <system.webServer> sectie die is toegevoegd aan het web.config-bestand door IIS Manager valt buiten de sectie van <location> de app die door de .NET Core SDK wordt toegevoegd wanneer de app wordt gepubliceerd. Omdat de sectie buiten het <location> knooppunt wordt toegevoegd, worden de instellingen voor zowel de huidige app als de sub-apps overgenomen. Om overname te voorkomen, verplaatst u de toegevoegde <security> sectie binnen de <location><system.webServer> sectie die door de .NET Core SDK is opgegeven.

  Wanneer IIS Manager wordt gebruikt om de IIS-configuratie toe te voegen, is dit alleen van invloed op het web.config-bestand van de app op de server. Een volgende implementatie van de app kan de instellingen op de server overschrijven als de kopie van de server van web.config wordt vervangen door het web.config-bestand van het project. Gebruik een van de volgende methoden om de instellingen te beheren:

  • Gebruik IIS-beheer om de instellingen in het web.config-bestand opnieuw in te stellen nadat het bestand is overschreven bij de implementatie.
  • Voeg een web.config-bestand lokaal aan de app toe met de instellingen.

Kestrel

Het Microsoft.AspNetCore.Authentication.Negotiate NuGet-pakket kan worden gebruikt om Kestrel Windows-verificatie te ondersteunen met negotiate en Kerberos in Windows, Linux en macOS.

Waarschuwing

Referenties kunnen worden behouden over meerdere aanvragen op een verbinding. Onderhandelen over verificatie mag niet worden gebruikt met proxy's, tenzij de proxy een 1:1-verbindingsaffiniteit (een permanente verbinding) onderhoudt met Kestrel.

Opmerking

De Negotiate-handler detecteert of de onderliggende server systeemeigen Windows-verificatie ondersteunt en of deze is ingeschakeld. Als de server Ondersteuning biedt voor Windows-verificatie, maar deze is uitgeschakeld, wordt er een fout gegenereerd waarin u wordt gevraagd de server-implementatie in te schakelen. Wanneer Windows-verificatie is ingeschakeld op de server, stuurt de negotiate-handler op transparante wijze verificatieaanvragen door.

Verificatie is ingeschakeld door de volgende gemarkeerde code voor Program.cs:

using Microsoft.AspNetCore.Authentication.Negotiate;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
   .AddNegotiate();

builder.Services.AddAuthorization(options =>
{
    options.FallbackPolicy = options.DefaultPolicy;
});
builder.Services.AddRazorPages();

var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

app.MapRazorPages();

app.Run();

De voorgaande code is gegenereerd door de sjabloon ASP.NET Basispagina's Razor met Windows-verificatie opgegeven. De volgende API's worden gebruikt in de voorgaande code:

• AddAuthentication
• AddNegotiate
• UseAuthentication

Kerberos-verificatie en op rollen gebaseerd toegangsbeheer (RBAC)

Kerberos-verificatie in Linux of macOS biedt geen rolgegevens voor een geverifieerde gebruiker. Als u rol- en groepsgegevens wilt toevoegen aan een Kerberos-gebruiker, moet de verificatiehandler worden geconfigureerd om de rollen op te halen uit een LDAP-domein. In de meest eenvoudige configuratie wordt alleen een LDAP-domein opgegeven voor query's en wordt de context van de geverifieerde gebruiker gebruikt om een query uit te voeren op het LDAP-domein:

using Microsoft.AspNetCore.Authentication.Negotiate;
using System.Runtime.InteropServices;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
    .AddNegotiate(options =>
    {
        if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
        {
            options.EnableLdap("contoso.com");
        }
    });

Voor sommige configuraties zijn mogelijk specifieke referenties vereist om een query uit te voeren op het LDAP-domein. De inloggegevens kunnen worden gespecificeerd in de volgende gemarkeerde opties.

using Microsoft.AspNetCore.Authentication.Negotiate;
using System.Runtime.InteropServices;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
        .AddNegotiate(options =>
        {
            if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
            {
                options.EnableLdap(settings =>
                {
                    settings.Domain = "contoso.com";
                    settings.MachineAccountName = "machineName";
                    settings.MachineAccountPassword =
                                      builder.Configuration["Password"];
                });
            }
        });

builder.Services.AddRazorPages();

Standaard lost de authenticatie-handler bij onderhandelen geneste domeinen op. In een grote of gecompliceerde LDAP-omgeving kan het oplossen van geneste domeinen leiden tot een trage zoekactie of veel geheugen dat voor elke gebruiker wordt gebruikt. Geneste domeinresolutie kan worden uitgeschakeld door de IgnoreNestedGroups optie.

Anonieme aanvragen zijn toegestaan. Gebruik ASP.NET Kernautorisatie om anonieme aanvragen voor verificatie uit te dagen.

Configuratie van Windows-omgeving

De Microsoft.AspNetCore.Authentication.Negotiate API voert verificatie van de gebruikersmodus uit. Service Principal Names (SPN's) moeten worden toegevoegd aan het gebruikersaccount waarop de service wordt uitgevoerd, niet aan het computeraccount. Voer setspn -S HTTP/myservername.mydomain.com myuser uit in een shell met beheeropdrachten.

Kerberos versus NTLM

Het onderhandelingspakket Kestrel voor ASP.NET Core probeert Kerberos te gebruiken. Dit is een veiliger en peformant verificatieschema dan NTLM:

using Microsoft.AspNetCore.Authentication.Negotiate;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
   .AddNegotiate();

builder.Services.AddAuthorization(options =>
{
    options.FallbackPolicy = options.DefaultPolicy;
});
builder.Services.AddRazorPages();

var app = builder.Build();

NegotiateDefaults.AuthenticationScheme geeft Kerberos op omdat dit de standaardwaarde is.

IIS, IISExpress en Kestrel ondersteunen zowel Kerberos als NTLM.

Het controleren van de WWW-Authenticate: header met IIS of IISExpress met een hulpprogramma zoals Fiddler toont Negotiate ofwel NTLM.

Kestrel toont alleen WWW-Authenticate: Negotiate

De WWW-Authenticate: Negotiate header betekent dat de server NTLM of Kerberos kan gebruiken. Kestrelvereist het voorvoegsel van deNegotiate header, maar biedt geen ondersteuning voor het rechtstreeks opgeven NTLM van headers voor aanvraag- of antwoordverificatie. NTLM wordt ondersteund in Kestrel, maar moet worden verzonden als Negotiate.

Om te zien of NTLM of Kerberos wordt gebruikt, decodeert u de header met Base64 en toont deze Kestrel of NTLM. HTTP geeft aan dat Kerberos is gebruikt.

Configuratie van Linux- en macOS-omgeving

Instructies voor het toevoegen van een Linux- of macOS-computer aan een Windows-domein zijn beschikbaar in azure Data Studio verbinden met uw SQL Server met behulp van Windows-verificatie - Kerberos-artikel . Met de instructies maakt u een computeraccount voor de Linux-machine in het domein. SPN's moeten worden toegevoegd aan dat computeraccount.

Opmerking

Wanneer u de richtlijnen in het artikel Connect Azure Data Studio met uw SQL Server gebruiken Windows-verificatie - Kerberos opvolgt, vervangt u python-software-properties door python3-software-properties indien nodig.

Zodra de Linux- of macOS-machine is toegevoegd aan het domein, zijn aanvullende stappen vereist om een keytab-bestand met de SPN's op te geven:

• Voeg op de domeincontroller nieuwe SPN's voor de webservice toe aan het computeraccount:
  • setspn -S HTTP/mywebservice.mydomain.com mymachine
  • setspn -S HTTP/mywebservice@MYDOMAIN.COM mymachine
• Gebruik ktpass om een keytab-bestand te genereren:
  • ktpass -princ HTTP/mywebservice.mydomain.com@MYDOMAIN.COM -pass myKeyTabFilePassword -mapuser MYDOMAIN\mymachine$ -pType KRB5_NT_PRINCIPAL -out c:\temp\mymachine.HTTP.keytab -crypto AES256-SHA1
  • Sommige velden moeten worden opgegeven in hoofdletters zoals aangegeven.
• Kopieer het keytab-bestand naar de Linux- of macOS-computer.
• Selecteer het keytab-bestand via een omgevingsvariabele: export KRB5_KTNAME=/tmp/mymachine.HTTP.keytab
• Aanroepen klist om de SPN's weer te geven die momenteel beschikbaar zijn voor gebruik.

Opmerking

Een keytab-bestand bevat referenties voor domeintoegang en moet dienovereenkomstig worden beveiligd.

HTTP.sys

HTTP.sys ondersteunt Windows-verificatie in kernelmodus met behulp van Negotiate, NTLM of Basisverificatie.

Met de volgende code wordt verificatie toegevoegd en wordt de webhost van de app geconfigureerd voor het gebruik van HTTP.sys met Windows-verificatie:

using Microsoft.AspNetCore.Server.HttpSys;
using System.Runtime.InteropServices;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(HttpSysDefaults.AuthenticationScheme);

if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
{
    builder.WebHost.UseHttpSys(options =>
        {
            options.Authentication.Schemes =
                AuthenticationSchemes.NTLM |
                AuthenticationSchemes.Negotiate;
            options.Authentication.AllowAnonymous = false;
        });
}

Opmerking

HTTP.sys delegeert naar Kernel Mode-authenticatie met het Kerberos-authenticatieprotocol. Verificatie van de gebruikersmodus wordt niet ondersteund met Kerberos en HTTP.sys. Het computeraccount moet worden gebruikt om het Kerberos-token/ticket dat is verkregen uit Active Directory te ontsleutelen en door de client door te sturen naar de server om de gebruiker te verifiëren. Registreer de SPN (Service Principal Name) voor de host, niet de gebruiker van de app.

Opmerking

HTTP.sys wordt niet ondersteund in Nano Server versie 1709 of hoger. Als u Windows-verificatie en HTTP.sys wilt gebruiken met Nano Server, gebruikt u een Server Core-container (microsoft/windowsservercore) (zie https://hub.docker.com/_/microsoft-windows-servercore). Zie Wat is de serverkerninstallatieoptie in Windows Server voor meer informatie over Server Core.

Gebruikers autoriseren

De configuratiestatus van anonieme toegang bepaalt de manier waarop de [Authorize] en [AllowAnonymous] kenmerken in de app worden gebruikt. In de volgende twee secties wordt uitgelegd hoe u de niet-toegestane en toegestane configuratiestatussen van anonieme toegang kunt afhandelen.

Anonieme toegang niet toestaan

Wanneer Windows-verificatie is ingeschakeld en anonieme toegang is uitgeschakeld, hebben de [Authorize] kenmerken [AllowAnonymous] geen effect. Als een IIS-site is geconfigureerd om anonieme toegang niet toe te laten, bereikt de aanvraag de app nooit. Daarom is het [AllowAnonymous] kenmerk niet van toepassing.

Anonieme toegang toestaan

Wanneer zowel Windows-verificatie als anonieme toegang zijn ingeschakeld, gebruikt u de [Authorize] en [AllowAnonymous] kenmerken. Met [Authorize] het kenmerk kunt u eindpunten van de app beveiligen waarvoor verificatie is vereist. Het [AllowAnonymous] kenmerk overschrijft het [Authorize] kenmerk in apps die anonieme toegang toestaan. Zie Eenvoudige autorisatie in ASP.NET Core voor details van kenmerkgebruik.

Opmerking

Standaard krijgen gebruikers die geen autorisatie hebben voor toegang tot een pagina een leeg HTTP 403-antwoord te zien. De StatusCodePages Middleware kan worden geconfigureerd om gebruikers een betere 'Toegang geweigerd'-ervaring te bieden.

Imitatie

ASP.NET Core implementeert geen imitatie. Apps worden uitgevoerd met de identiteit van de app voor alle aanvragen, met behulp van een app-pool of procesidentiteit. Als de app een actie moet uitvoeren namens een gebruiker, gebruikt WindowsIdentity.RunImpersonated of RunImpersonatedAsync in een terminal inline middleware in Program.cs. Voer één actie uit in deze context en sluit vervolgens de context.

app.Run(async (context) =>
{
    try
    {
        var user = (WindowsIdentity)context.User.Identity!;

        await context.Response
            .WriteAsync($"User: {user.Name}\tState: {user.ImpersonationLevel}\n");

        await WindowsIdentity.RunImpersonatedAsync(user.AccessToken, async () =>
        {
            var impersonatedUser = WindowsIdentity.GetCurrent();
            var message =
                $"User: {impersonatedUser.Name}\t" +
                $"State: {impersonatedUser.ImpersonationLevel}";

            var bytes = Encoding.UTF8.GetBytes(message);
            await context.Response.Body.WriteAsync(bytes, 0, bytes.Length);
        });
    }
    catch (Exception e)
    {
        await context.Response.WriteAsync(e.ToString());
    }
});

Hoewel het Microsoft.AspNetCore.Authentication.Negotiate pakket verificatie inschakelt in Windows, Linux en macOS, wordt imitatie alleen ondersteund in Windows.

Claims transformaties

Wanneer u host met IIS, AuthenticateAsync wordt deze niet intern aangeroepen om een gebruiker te initialiseren. Daarom is een IClaimsTransformation implementatie die na elke verificatie wordt gebruikt om claims te transformeren, niet standaard geactiveerd. Voor meer informatie en een codevoorbeeld waarmee claimtransformaties worden geactiveerd, zie Verschillen tussen in-proces en uit-proces hosting.

Aanvullende bronnen

• dotnet publiceren
• Host ASP.NET Core op Windows met IIS
• ASP.NET Core Module (ANCM) voor IIS-
• Visual Studio-publicatieprofielen (.pubxml) voor ASP.NET Core-app-implementatie