Delen via


Beveiligde web-API: codeconfiguratie

Als u de code voor uw beveiligde web-API wilt configureren, begrijpt u het volgende:

  • Wat definieert API's als beveiligd.
  • Een Bearer-token configureren.
  • Het token valideren.

Wat definieert ASP.NET en ASP.NET Core-API's als beveiligd?

Net als web-apps worden ASP.NET en ASP.NET Core-web-API's beveiligd omdat hun controlleracties worden voorafgegaan door het kenmerk [Autoriseren]. De controlleracties kunnen alleen worden aangeroepen als de API wordt aangeroepen met een geautoriseerde identiteit.

Denk na over de volgende vragen:

  • Alleen een app kan een web-API aanroepen. Hoe weet de API de identiteit van de app die deze aanroept?
  • Als de app de API aanroept namens een gebruiker, wat is de identiteit van de gebruiker?

Bearer-token

Het bearer-token dat is ingesteld in de header wanneer de app wordt aangeroepen, bevat informatie over de app-identiteit. Het bevat ook informatie over de gebruiker, tenzij de web-app service-naar-service-aanroepen van een daemon-app accepteert.

Hier volgt een C#-codevoorbeeld met een client die de API aanroept nadat er een token is verkregen met de Microsoft Authentication Library voor .NET (MSAL.NET):

var scopes = new[] {$"api://.../access_as_user"};
var result = await app.AcquireToken(scopes)
                      .ExecuteAsync();

httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.AccessToken);

// Call the web API.
HttpResponseMessage response = await _httpClient.GetAsync(apiUri);

Belangrijk

Een clienttoepassing vraagt het Bearer-token aan bij het Microsoft Identity Platform voor de web-API. De API is de enige toepassing die het token moet verifiëren en de claims moet weergeven die het bevat. Client-apps mogen nooit proberen de claims in tokens te inspecteren.

In de toekomst vereist de web-API mogelijk dat het token wordt versleuteld. Deze vereiste voorkomt toegang voor client-apps die toegangstokens kunnen bekijken.

JwtBearer-configuratie

In deze sectie wordt beschreven hoe u een Bearer-token configureert.

Configuratiebestand

U moet de TenantId enige opgeven als u toegangstokens van één tenant (Line-Of-Business-app) wilt accepteren. Anders kan het overblijven als common. De verschillende waarden kunnen zijn:

  • Een GUID (tenant-id = map-id)
  • common kan elke organisatie en persoonlijke accounts zijn
  • organizations kan elke organisatie zijn
  • consumers zijn persoonlijke Microsoft-accounts
{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Een aangepaste URI voor app-id's gebruiken voor een web-API

Als u de standaard-app-id-URI hebt geaccepteerd die door Azure Portal wordt voorgesteld, hoeft u de doelgroep niet op te geven (zie de URI en bereiken van de toepassings-id). Voeg anders een Audience eigenschap toe waarvan de waarde de app-id-URI voor uw web-API is. Dit begint meestal met api://.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common",
    "Audience": "Enter_the_Application_ID_URI_here"
  },
}

Initialisatie van code

Wanneer een app wordt aangeroepen op een controlleractie met een kenmerk [Autoriseren] , ASP.NET en ASP.NET Core het toegangstoken uit het Bearer-token van de Autorisatie-header extraheren. Het toegangstoken wordt vervolgens doorgestuurd naar de JwtBearer-middleware, die Microsoft IdentityModel Extensions voor .NET aanroept.

Microsoft.Identity.Web

Microsoft raadt u aan het NuGet-pakket Microsoft.Identity.Web te gebruiken bij het ontwikkelen van een web-API met ASP.NET Core.

Microsoft.Identity.Web biedt de lijm tussen ASP.NET Core, de verificatie-middleware en de Microsoft Authentication Library (MSAL) voor .NET. Het biedt een duidelijkere, robuustere ontwikkelaarservaring en maakt gebruik van de kracht van het Microsoft Identity Platform en Azure AD B2C.

ASP.NET voor .NET 6.0

Als u een nieuw web-API-project wilt maken dat gebruikmaakt van Microsoft.Identity.Web, gebruikt u een projectsjabloon in de .NET 6.0 CLI of Visual Studio.

Dotnet core CLI

# Create new web API that uses Microsoft.Identity.Web
dotnet new webapi --auth SingleOrg

Visual Studio: als u een web-API-project wilt maken in Visual Studio, selecteert u File>New>Project>ASP.NET Core Web API.

Zowel de .NET CLI- als de Visual Studio-projectsjablonen maken een Program.cs-bestand dat lijkt op dit codefragment. Let op Microsoft.Identity.Web het gebruik van richtlijn en de regels die verificatie en autorisatie bevatten.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

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

app.MapControllers();

app.Run();