API web protégée : Configuration de code

Microsoft vous recommande d’utiliser le package NuGet Microsoft.Identity.Web lors du développement d’une API web avec ASP.NET Core.

Microsoft.Identity.Web fournit le ciment entre ASP.NET Core, l’intergiciel d’authentification et la bibliothèque d’authentification Microsoft (MSAL) pour .NET. Il favorise une expérience développeur plus claire et plus robuste, et tire parti de la puissance de la plateforme d’identités Microsoft et d’Azure AD B2C.

ASP.NET pour .NET 6.0

Pour créer un projet d’API web qui utilise Microsoft.Identity.Web, utilisez un modèle de projet dans l’interface CLI .NET 6.0 ou Visual Studio.

CLI Dotnet core

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

Visual Studio - Pour créer un projet d’API web dans Visual Studio, sélectionnez Fichier>Nouveau>Projet>API web ASP.NET Core.

Les modèles de projet .NET CLI et Visual Studio créent un fichier Program.cs, qui ressemble à cet extrait de code. Notez la directive using Microsoft.Identity.Web ainsi que les lignes contenant l’authentification et l’autorisation.

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 vous recommande d’utiliser le package NuGet Microsoft.Identity.Web.OWIN lors du développement d’une API web avec ASP.NET.

Microsoft.Identity.Web.OWIN fournit le ciment entre ASP.NET, l’intergiciel d’authentification ASP.NET et la bibliothèque d’authentification Microsoft (MSAL) pour .NET. Il favorise une expérience développeur plus claire et plus robuste, et tire parti de la puissance de la plateforme d’identités Microsoft et d’Azure AD B2C.

Il utilise le même fichier de configuration que ASP.NET Core (appsettings.json) et vous devez vous assurer que ce fichier est copié avec la sortie de votre projet (copie de propriété toujours dans les propriétés du fichier dans Visual Studio ou dans .csproj)

Microsoft.Identity.Web.OWIN ajoute une méthode d’extension à IAppBuilder nommée AddMicrosoftIdentityWebApi. Cette méthode prend comme paramètre un instance de OwinTokenAcquirerFactory que vous obtenez l’appel OwinTokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>() et qui fait apparaître un instance auquel vous pouvez ajouter de IServiceCollection nombreux services pour appeler des API en aval ou configurer le cache de jetons.

Voici un exemple de code pour Startup.Auth.cs. Le code complet est disponible à partir de 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();
        }
    }
}

--

Validation du jeton

Dans l’extrait de code précédent, l’intergiciel JwtBearer, tout comme le middleware OpenID Connect dans des applications web, valide le jeton en fonction de la valeur de TokenValidationParameters. Le jeton est déchiffré si nécessaire, les revendications extraites et la signature vérifiée. L’intergiciel valide ensuite le jeton en vérifiant les points suivants :

• Audience: Le jeton est destiné à l’API web.
• Sub : Il a été émis pour une application autorisée à appeler l’API web.
• Émetteur : Il a été émis par un service d’émission de jeton de sécurité (STS) approuvé.
• Expiration : Sa durée de vie s’inscrit dans la plage valide.
• Signature : Il n’a pas été falsifié.

Il peut également y avoir des validations spéciales. Par exemple, il est possible de valider le fait que les clés de signature, quand elles sont incorporées dans un jeton, sont approuvées et que le jeton n’est pas en cours de réexécution. Enfin, certains protocoles nécessitent des validations spécifiques.

Validateurs

Les étapes de validation sont capturées dans des validateurs qui sont fournis par la bibliothèque open source Microsoft IdentityModel Extensions for .NET. Les validateurs sont définis dans le fichier source de la bibliothèque Microsoft.IdentityModel.Tokens/Validators.cs.

Ce tableau décrit les validateurs :

Personnalisation de la validation des jetons

Les validateurs sont associés aux propriétés de la classe TokenValidationParameters. Les propriétés sont initialisées à partir de la configuration ASP.NET et ASP.NET Core.

Dans la plupart des cas, vous n’avez pas besoin de modifier les paramètres. Les applications qui ne sont pas à locataire unique sont des exceptions. Ces applications web acceptent des utilisateurs de toute organisation ou de comptes Microsoft personnels. Dans ce cas, les émetteurs doivent être validés. Microsoft.Identity.Web s’occupe également de la validation de l’émetteur.

Dans ASP.NET Core, si vous souhaitez personnaliser les paramètres de validation du jeton, utilisez l’extrait de code suivant dans votre Startup.cs :

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

Pour le MVC d’ASP.NET, l’exemple de code suivant montre comment effectuer une validation de jeton personnalisée :

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

Validation des jetons dans Azure Functions

Vous pouvez également valider les jetons d’accès entrants dans Azure Functions. Vous trouverez des exemples de cette validation dans les exemples de code suivants sur 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)

Étapes suivantes

Passez à l’article suivant de ce scénario, Vérifier les étendues et les rôles d’application dans votre code.