Quickstart: Een ASP.NET Core-web-API beveiligen met het Microsoft Identity Platform

Artikel
07/16/2024

Welkom. Dit is waarschijnlijk niet de pagina die u verwachtte te zien. Terwijl we aan een oplossing voor dit probleem werken, kunt u met deze koppeling naar het juiste artikel gaan:

Quickstart: Een ASP.NET Core-web-API aanroepen die wordt beveiligd door het Microsoft Identity Platform

Onze excuses voor het ongemak en bedankt voor uw geduld tijdens onze inspanningen om dit probleem op te lossen.

In de volgende quickstart wordt een voorbeeld van ASP.NET Core-web-API-code gebruikt om te laten zien hoe u de toegang tot resources tot geautoriseerde accounts beperkt. Het voorbeeld ondersteunt autorisatie van persoonlijke Microsoft-accounts en -accounts in elke Microsoft Entra-organisatie.

Vereisten

Azure-account met een actief abonnement. Gratis een account maken
Microsoft Entra-tenant
Een minimale vereiste van .NET 6.0 SDK
Visual Studio 2022 of Visual Studio Code

Stap 1: De toepassing registreren

Registreer eerst de web-API in uw Microsoft Entra-tenant en voeg een bereik toe door de volgende stappen uit te voeren:

Meld u als toepassingsbeheerder aan bij het Microsoft Entra-beheercentrum .
Blader naar identiteitstoepassingen>> App-registraties.
Selecteer Nieuwe registratie.
Voer bij Naam een naam in voor de toepassing. Voer bijvoorbeeld AspNetCoreWebApi-Quickstart in. Gebruikers van de app zien deze naam en kunnen later worden gewijzigd.
Selecteer Registreren.
Selecteer onder Beheren Een API beschikbaar maken>Een bereik toevoegen. Accepteer voor de URI van de toepassings-id de standaardinstelling door Opslaan en doorgaan te selecteren en voer vervolgens de volgende gegevens in:

Naam van bereik: access_as_user
Wie kan toestemming geven?: beheerders en gebruikers
Weergavenaam van beheerderstoestemming: Access AspNetCoreWebApi-Quickstart
Beschrijving van beheerderstoestemming: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
Weergavenaam van gebruikerstoestemming: Access AspNetCoreWebApi-Quickstart
Beschrijving van gebruikerstoestemming: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
Status: ingeschakeld

Selecteer Bereik toevoegen om de toevoeging van het bereik te volt ooien.

Stap 2: Het ASP.NET Core-project downloaden

De ASP.NET Core-oplossing downloaden van GitHub.

Notitie

Het codevoorbeeld is momenteel gericht op ASP.NET Core 3.1. Het voorbeeld kan worden bijgewerkt voor gebruik van .NET Core 6.0 en wordt behandeld in de volgende stappen: Werk de voorbeeldcode bij naar ASP.NET Core 6.0. Deze quickstart wordt binnenkort afgeschaft en wordt bijgewerkt voor gebruik van .NET 6.0.

Stap 3: het ASP.NET Core-project configureren

In deze stap wordt de voorbeeldcode geconfigureerd om te werken met de app-registratie die eerder is gemaakt.

Pak het bestand .zip uit naar een lokale map die zich dicht bij de hoofdmap van de schijf bevindt om fouten te voorkomen die worden veroorzaakt door padlengtebeperkingen in Windows. Pak bijvoorbeeld uit naar C:\Azure-Samples.
Open de oplossing in de map webapi in de code-editor.
Vervang in appsettings.json de waarden van ClientIden TenantId.
```
"ClientId": "Enter_the_Application_Id_here",
"TenantId": "Enter_the_Tenant_Info_Here"
```
- Enter_the_Application_Id_Here is de toepassings-id (client) voor de geregistreerde toepassing.
- Vervang Enter_the_Tenant_Info_Here door een van de volgende opties:
  - Als de toepassing alleen accounts in deze organisatiemap ondersteunt, vervangt u deze waarde door de map-id (tenant) (een GUID) of tenantnaam (bijvoorbeeldcontoso.onmicrosoft.com). De map-id (tenant) vindt u op de overzichtspagina van de app.
  - Als de toepassing accounts in een organisatiemap ondersteunt, vervangt u deze waarde door organizations.
  - Als de toepassing alle microsoft-accountgebruikers ondersteunt, laat u deze waarde staan als common.

Wijzig voor deze Snelstart geen andere waarden in het bestand appSettings.json.

Stap 4: De voorbeeldcode bijwerken naar ASP.NET Core 6.0

Volg deze stappen om dit codevoorbeeld bij te werken voor ASP.NET Core 6.0:

Open webapi.csproj
Verwijder de volgende regel:

<TargetFramework>netcoreapp3.1</TargetFramework>

Voeg de volgende regel toe:

<TargetFramework>netcoreapp6.0</TargetFramework>

Deze stap zorgt ervoor dat het voorbeeld gericht is op het .NET Core 6.0-framework.

Stap 5: Het voorbeeld uitvoeren

Open een terminal en wijzig de map in de projectmap.
```
cd webapi
```
Voer de volgende opdracht uit om de oplossing te bouwen:

dotnet run

Als de build is geslaagd, wordt de volgende uitvoer weergegeven:

Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: https://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

Hoe het voorbeeld werkt

Opstartklasse

De Middleware Microsoft.AspNetCore.Authentication maakt gebruik van een Startup klasse die wordt uitgevoerd wanneer het hostingproces wordt gestart. In de methode ConfigureServices wordt de AddMicrosoftIdentityWebApiextensiemethode geleverd door Microsoft.Identity.Web aangeroepen.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

Met de methode AddAuthentication() wordt de service geconfigureerd voor het toevoegen van JwtBearer-gebaseerde verificatie.

De regel die de Autorisatie van het Microsoft Identity Platform bevat .AddMicrosoftIdentityWebApi , wordt toegevoegd aan de web-API. Het wordt vervolgens geconfigureerd om toegangstokens te valideren die zijn uitgegeven door het Microsoft Identity Platform op basis van de informatie in de AzureAD sectie van het appsettings.json-configuratiebestand :

Sleutel appSettings.json	Beschrijving
`ClientId`	Toepassings-id (client) van de geregistreerde toepassing.
`Instance`	STS-eindpunt (Security Token Service) voor de gebruiker te verifiëren. Deze waarde is doorgaans `https://login.microsoftonline.com/`, wat de openbare Azure-cloud aangeeft.
`TenantId`	De naam van uw tenant of de tenant-id (een GUID) of `common` om gebruikers aan te melden met werk- of schoolaccounts of persoonlijke Microsoft-accounts.

De methode Configure() bevat twee belangrijke methoden, app.UseAuthentication() en app.UseAuthorization(), waarmee de benoemde functionaliteit wordt ingeschakeld:

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

Een controller, de methode van een controller of een Razor-pagina beveiligen

Een controller- of controllermethode kan worden beveiligd met behulp van het [Authorize] kenmerk. Dit kenmerk beperkt de toegang tot de controller of methoden door alleen geverifieerde gebruikers toe te staan. Een verificatievraag kan worden gestart voor toegang tot de controller als de gebruiker niet is geverifieerd.

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

Validatie van bereik in de controller

De code in de API controleert of de vereiste bereiken zich in het token bevinden met behulp van HttpContext.VerifyUserHasAnyAcceptedScope> (scopeRequiredByApi);:

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        // The web API will only accept tokens 1) for users, and 2) having the "access_as_user" scope for this API
        static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

            // some code here
        }
    }
}

Help en ondersteuning

Als u hulp nodig hebt, een probleem wilt melden of meer informatie wilt over uw ondersteuningsopties, raadpleegt u Hulp en ondersteuning voor ontwikkelaars.

Volgende stappen

De volgende GitHub-opslagplaats bevat de ASP.NET Core web-API-codevoorbeeldinstructies en meer voorbeelden die laten zien hoe u het volgende kunt bereiken:

Verificatie toevoegen aan een nieuwe ASP.NET Core-web-API.
Roep de web-API aan vanuit een bureaubladtoepassing.
Roep downstream-API's aan, zoals Microsoft Graph en andere Microsoft-API's.

ASP.NET Core Web API-handleidingen op GitHub

Delen via