Beveiligde web-API: codeconfiguratie

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 >

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();

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

Microsoft.Identity.Web.OWIN biedt de lijm tussen ASP.NET, de ASP.NET 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.

Het gebruikt hetzelfde configuratiebestand als ASP.NET Core (appsettings.json) en u moet ervoor zorgen dat dit bestand wordt gekopieerd met de uitvoer van uw project (eigenschap kopiëren altijd in de bestandseigenschappen in Visual Studio of in de .csproj)

Microsoft.Identity.Web.OWIN voegt een uitbreidingsmethoden toe aan IAppBuilder met de naam AddMicrosoftIdentityWebApi. Deze methode neemt als parameter een exemplaar van OwinTokenAcquirerFactory dat u aanroept OwinTokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>() en die een exemplaar weergeeft waarvan IServiceCollection u veel services kunt toevoegen om downstream-API's aan te roepen of de tokencache te configureren.

Hier volgt een voorbeeldcode voor Startup.Auth.cs. De volledige code is beschikbaar via tests/DevApps/aspnet-mvc/OwinWebApp

using Microsoft.Owin.Security;
using Microsoft.Owin.Security.Cookies;
using Owin;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Client;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web.OWIN;
using System.Web.Services.Description;

namespace OwinWebApp
{
    public partial class Startup
    {
        public void ConfigureAuth(IAppBuilder app)
        {
            app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);
            app.UseCookieAuthentication(new CookieAuthenticationOptions());

            OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

            app.AddMicrosoftIdentityWebApp(factory);
            factory.Services
                .Configure<ConfidentialClientApplicationOptions>(options => { options.RedirectUri = "https://localhost:44386/"; })
                .AddMicrosoftGraph()
                .AddDownstreamApi("DownstreamAPI1", factory.Configuration.GetSection("DownstreamAPI"))
                .AddInMemoryTokenCaches();
            factory.Build();
        }
    }
}

--

Tokenvalidatie

In het voorgaande codefragment valideert de JwtBearer-middleware, zoals de OpenID Connect-middleware in web-apps, het token op basis van de waarde van TokenValidationParameters. Het token wordt indien nodig ontsleuteld, de claims worden geëxtraheerd en de handtekening wordt geverifieerd. De middleware valideert vervolgens het token door te controleren op deze gegevens:

• Doelgroep: Het token is bedoeld voor de web-API.
• Sub: Deze is uitgegeven voor een app die de web-API mag aanroepen.
• Uitgever: Het is uitgegeven door een vertrouwde beveiligingstokenservice (STS).
• Verloopdatum: de levensduur is binnen het bereik.
• Handtekening: Er is niet geknoeid met.

Er kunnen ook speciale validaties zijn. Het is bijvoorbeeld mogelijk om te valideren dat ondertekeningssleutels, wanneer deze zijn ingesloten in een token, worden vertrouwd en dat het token niet opnieuw wordt afgespeeld. Ten slotte vereisen sommige protocollen specifieke validaties.

Validatoren

De validatiestappen worden vastgelegd in validators, die worden geleverd door de Microsoft IdentityModel Extensions voor .NET opensource-bibliotheek. De validaties worden gedefinieerd in het bibliotheekbronbestand Microsoft.IdentityModel.Tokens/Validators.cs.

In deze tabel worden de validaties beschreven:

Tokenvalidatie aanpassen

De validaties zijn gekoppeld aan eigenschappen van de klasse TokenValidationParameters . De eigenschappen worden geïnitialiseerd vanuit de ASP.NET- en ASP.NET Core-configuratie.

In de meeste gevallen hoeft u de parameters niet te wijzigen. Apps die geen enkele tenant zijn, zijn uitzonderingen. Deze web-apps accepteren gebruikers van elke organisatie of van persoonlijke Microsoft-accounts. In dit geval moeten verleners worden gevalideerd. Microsoft.Identity.Web zorgt ook voor de validatie van de verlener.

Als u in ASP.NET Core de parameters voor tokenvalidatie wilt aanpassen, gebruikt u het volgende fragment in uw Startup.cs:

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddMicrosoftIdentityWebApi(Configuration);
services.Configure<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme, options =>
{
  options.TokenValidationParameters.ValidAudiences = new[] { /* list of valid audiences */};
});

Voor ASP.NET MVC ziet u in het volgende codevoorbeeld hoe u aangepaste tokenvalidatie kunt uitvoeren:

https://github.com/azure-samples/active-directory-dotnet-webapi-manual-jwt-validation

Tokenvalidatie in Azure Functions

U kunt ook binnenkomende toegangstokens valideren in Azure Functions. Voorbeelden van dergelijke validatie vindt u in de volgende codevoorbeelden op GitHub:

• .NET: Azure-Samples/ms-identity-dotnet-webapi-azurefunctions
• Node.js: Azure-Samples/ms-identity-nodejs-webapi-azurefunctions
• Python: Azure-Samples/ms-identity-python-webapi-azurefunctions)

Volgende stappen

Ga verder met het volgende artikel in dit scenario, Scopes en app-rollen verifiëren in uw code.