Démarrage rapide : Protéger une API web ASP.NET Core avec la plateforme d’identités Microsoft

Le guide de démarrage rapide suivant utilise un exemple de code d’API web ASP.NET Core pour montrer comment restreindre l’accès aux ressources aux comptes autorisés. L’exemple prend en charge l’autorisation des comptes Microsoft personnels et des comptes dans n’importe quelle organisation Microsoft Entra.

Prérequis

• Compte Azure avec un abonnement actif. Créez un compte gratuitement.
• Locataire Microsoft Entra
• Configuration minimale requise : kit de développement logiciel (SDK) .NET 6.0
• Visual Studio 2022 ou Visual Studio Code

Étape 1 : Enregistrement de l’application

Tout d’abord, inscrivez l’API web dans votre tenant Microsoft Entra, puis ajoutez une étendue en effectuant les étapes suivantes :

1. Connectez-vous au centre d'administration Microsoft Entra au minimum en tant qu’Administrateur d'application.
2. Accédez à Identité>Applications>Inscriptions d’applications.
3. Sélectionnez Nouvelle inscription.
4. Dans Nom, entrez le nom de l’application. Par exemple, entrez AspNetCoreWebApi-Quickstart. Les utilisateurs de l’application peuvent voir ce nom, qui peut être modifié ultérieurement.
5. Sélectionnez Inscription.
6. Sous Gérer, sélectionnez Exposer une API>Ajouter une étendue. Pour l’URI d’ID d’application acceptez l’option par défaut en sélectionnant Enregistrer et continuer, puis entrez les informations suivantes :

• Nom de l’étendue : access_as_user
• Qui peut donner son consentement ? : Administrateurs et utilisateurs
• Nom d’affichage du consentement administrateur : Access AspNetCoreWebApi-Quickstart
• Description du consentement de l’administrateur : Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
• Nom d’affichage du consentement utilisateur : Access AspNetCoreWebApi-Quickstart
• Description du consentement de l’utilisateur : Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
• État : Activé

1. Sélectionnez Ajouter une étendue pour finaliser l’ajout de l’étendue.

Étape 2 : Télécharger le projet ASP.NET Core

Télécharger la solution ASP.NET Core à partir de GitHub.

L’exemple de code cible actuellement ASP.NET Core 3.1. L’exemple peut être mis à jour pour utiliser .NET Core 6.0 et est abordé dans les étapes suivantes : Mettez à jour l’exemple de code vers ASP.NET Core 6.0. Ce guide de démarrage rapide sera déconseillé dans un avenir proche et sera mis à jour pour utiliser .NET 6.0.

Étape 3 : Configurer le projet ASP.NET Core

Dans cette étape, l’exemple de code va être configuré pour qu’il fonctionne avec l’inscription d’application créée précédemment.

1. Extrayez le fichier .zip dans un dossier local proche de la racine du disque pour éviter les erreurs causées par les limitations de longueur de chemin d’accès sur Windows. Par exemple, extrayez-le dans C:\Azure-Samples.

2. Dans votre éditeur de code, ouvrez la solution qui est située dans le dossier webapi.

3. Dans appsettings.js, remplacez les valeurs de ClientId, etTenantId.

   "ClientId": "Enter_the_Application_Id_here",
   "TenantId": "Enter_the_Tenant_Info_Here"
   

   • Enter_the_Application_Id_Here est l’ID d’application (client) de l’application inscrite.
   • Remplacez Enter_the_Tenant_Info_Here par l’un des éléments suivants :
     • Si l’application prend en charge les Comptes dans cet annuaire organisationnel uniquement, remplacez cette valeur par l’ID de l’annuaire (locataire) (un GUID) ou par le nom du locataire (par exemple, contoso.onmicrosoft.com). L’ID de l’annuaire (locataire) se trouve dans la page Vue d’ensemble de l’application.
     • Si l’application prend en charge les Comptes dans un annuaire organisationnel, remplacez cette valeur par organizations.
     • Si l’application prend en charge Tous les utilisateurs de compte Microsoft, conservez la valeur common.

Pour ce guide de démarrage rapide, ne modifiez pas les autres valeurs du fichier appsettings.json.

Étape 4 : Mettre à jour l’exemple de code vers ASP.NET Core 6.0

Pour mettre à jour cet exemple de code pour cibler ASP.NET Core 6.0, suivez ces étapes :

1. Ouvrir webapi.csproj
2. Supprimez la ligne suivante :

<TargetFramework>netcoreapp3.1</TargetFramework>

1. Ajoutez la ligne suivante à sa place :

<TargetFramework>netcoreapp6.0</TargetFramework>

Cette étape garantit que l’exemple cible le framework .NET Core 6.0.

Étape 5 : Exécuter l’exemple

1. Ouvrez un terminal et remplacez le répertoire par le dossier du projet.

   cd webapi
   

2. Exécutez la commande suivante pour générer la solution :

dotnet run

Si la génération a réussi, la sortie suivante s’affiche :

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.
...

Fonctionnement de l’exemple

Classe de démarrage

Le middleware (intergiciel) Microsoft.AspNetCore.Authentication utilise une classe Startup qui s’exécute lors du démarrage du processus d’hébergement. Dans sa méthode ConfigureServices, la méthode d’extension AddMicrosoftIdentityWebApi fournie par Microsoft.Identity.Web est appelée.

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

La méthode AddAuthentication() configure le service pour ajouter l’authentification basée sur JwtBearer.

La ligne contenant .AddMicrosoftIdentityWebApi ajoute à l’API web l’autorisation de la plateforme d’identités Microsoft. Elle est ensuite configurée pour valider les jetons d’accès émis par la plateforme d’identités Microsoft en fonction des informations contenues dans la section AzureAD du fichier de configuration appsettings.json :

La méthode Configure() contient deux méthodes importantes, app.UseAuthentication() et app.UseAuthorization(), qui activent leurs fonctionnalités nommées :

// 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
}

Protéger un contrôleur, la méthode d’un contrôleur ou une page Razor

Un contrôleur ou des méthodes de contrôleur peuvent être protégés à l’aide de l’attribut [Authorize] . Cet attribut limite l’accès au contrôleur ou aux méthodes en autorisant uniquement les utilisateurs authentifiés. Une demande d’authentification peut alors être démarrée pour accéder au contrôleur si l’utilisateur n’est pas authentifié.

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

Validation de l’étendue dans le contrôleur

Le code de l’API vérifie ensuite que les étendues nécessaires se trouvent dans le jeton à l’aide de 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
        }
    }
}

Aide et support

Si vous avez besoin d’aide, si vous souhaitez signaler un problème ou si vous voulez en savoir plus sur vos options de support, consultez Aide et support pour les développeurs.

Étapes suivantes

Le dépôt GitHub suivant contient les exemples ASP.NET Core d’instructions de code d’API web et d’autres exemples qui montrent comment effectuer les opérations suivantes :

• Ajoutez l’authentification à une nouvelle API web ASP.NET Core.
• Appelez l’API web à partir d’une application de bureau.
• Appelez des API en aval comme Microsoft Graph et d’autres API Microsoft.