API web protégée : Configuration de code

  • Article

Pour configurer le code de votre API web protégée, vous devez comprendre ce qui suit :

  • Ce qui définit les API comme étant protégées.
  • Comment configurer un jeton du porteur.
  • Comment valider le jeton.

Qu’est-ce qui définit les API ASP.NET et ASP.NET Core comme étant protégées ?

Comme les applications web, les API web ASP.NET et ASP.NET Core sont protégées parce que leurs actions de contrôleur sont préfixées par l’attribut [Authorize]. Les actions de contrôleur peuvent être appelées uniquement si l’API est appelée avec une identité autorisée.

Considérez les questions suivantes :

  • Seule une application peut appeler une API web. Comment l’API connaît-elle l’identité de l’application qui l’appelle ?
  • Si l’application appelle l’API au nom d’un utilisateur, quelle est l’identité de celui-ci ?

Jeton du porteur

Le jeton du porteur qui est défini dans l’en-tête lorsque l’application est appelée contient des informations sur l’identité de l’application. Il contient également des informations sur l’utilisateur, sauf si l’application web accepte les appels de service à service à partir d’une application démon.

Voici un exemple de code C# qui présente un client appelant l’API après avoir acquis un jeton de la bibliothèque d’authentification Microsoft pour .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);

Important

Une application cliente demande le jeton du porteur à la plateforme d’identités Microsoft pour l’API web. L’API est la seule application qui doive vérifier le jeton et afficher les revendications qu’il contient. Les applications clientes ne doivent jamais tenter d’inspecter les revendications contenues dans les jetons

À l’avenir, l’API web pourrait exiger que le jeton soit chiffré. Cette exigence empêcherait l’accès des applications clientes capables d’afficher les jetons d’accès.

Configuration de JwtBearer

Cette section décrit comment configurer un jeton du porteur.

Fichier de configuration

Vous devez spécifier le TenantId seulement si vous souhaitez accepter des jetons d’accès à partir d’un locataire unique (application métier). Sinon, vous pouvez laisser la valeur common. Les différentes valeurs peuvent être :

  • Un GUID (ID de locataire = ID d’annuaire)
  • common peut être n’importe quelle organisation ou tout compte personnel
  • organizations peut être n’importe quelle organisation
  • Les consumers sont des comptes personnels Microsoft
{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Utilisation d’un URI d’ID d’application personnalisé pour une API web

Si vous avez accepté l’URI ID d’application par défaut proposé par le portail Azure, vous n’avez pas besoin de spécifier le public (consultez URI et étendues de l’ID d’application). Dans le cas contraire, ajoutez une propriété Audience dont la valeur est l’URI ID d’application de votre API web. Il commence généralement par api://.

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

Initialisation du code

Quand une application est appelée sur une action de contrôleur qui contient un attribut [Authorize], ASP.NET et ASP.NET Core extraient le jeton d’accès à partir du jeton du porteur dans l’en-tête d’autorisation. Le jeton d’accès est ensuite transmis à l’intergiciel JwtBearer qui appelle Microsoft IdentityModel Extensions pour .NET.

Microsoft.Identity.Web

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