Védett web API: Kódkonfiguráció

A következőkre vonatkozik: Munkaerő-bérlők (további információ)

A védett webes API kódjának konfigurálásához tekintse meg a következőket:

• Mi határozza meg az API-kat védettként.
• Meghatalmazási token konfigurálása.
• Hogyan érvényesítsük a jogkivonatot.

Elfogadott jogkivonat-verzió

A Microsoft Identitásplatform 1.0-s és 2.0-s verziós jogkivonatokat bocsáthat ki. További információ ezekről a tokenekről: Hozzáférési jogkivonatok.

Az API által elfogadható jogkivonat-verzió a támogatott fióktípusok kiválasztásától függ, amikor webes API-alkalmazásregisztrációt hoz létre az Azure Portalon.

• Ha a támogatott fióktípusok értéke bármely szervezeti címtárban és személyes Microsoft-fiókban (például Skype, Xbox, Outlook.com) található fiókok, az elfogadott jogkivonat-verziónak 2.0-s verziónak kell lennie.
• Ellenkező esetben az elfogadott jogkivonat verziója lehet 1.0-s verzió.

Az alkalmazás létrehozása után az alábbi lépések végrehajtásával határozhatja meg vagy módosíthatja az elfogadott jogkivonat verzióját:

1. A Microsoft Entra Felügyeleti központban válassza ki az alkalmazást, majd válassza a Jegyzék elemet.
2. Keresse meg az accessTokenAcceptedVersion tulajdonságot a jegyzékben.
3. Az érték megadja a Microsoft Entra számára, hogy a webes API melyik jogkivonat-verziót fogadja el.
   • Ha az érték 2, a webes API 2.0-s jogkivonatokat fogad el.
   • Ha az érték null, a web API 1.0-s jogkivonatokat fogad el.
4. Ha módosította a jogkivonat verzióját, válassza a Mentés lehetőséget.

A webes API megadja, hogy melyik jogkivonat-verziót fogadja el. Amikor egy ügyfél jogkivonatot kér a webes API-hoz a Microsoft Identitásplatform, az ügyfél egy jogkivonatot kap, amely jelzi, hogy a webes API melyik jogkivonat-verziót fogadja el.

Mi határozza meg a ASP.NET és ASP.NET Core API-kat védettként?

A webalkalmazásokhoz hasonlóan a ASP.NET és ASP.NET Core webes API-k is védettek, mert a vezérlőműveleteik előtagja az [Engedélyezés] attribútum. A vezérlőműveletek csak akkor hívhatók meg, ha az API-t hitelesített identitással hívják meg.

A következő kérdéseket kell figyelembe venni:

• Csak egy alkalmazás hívhat meg webes API-t. Honnan tudja az API a meghívó alkalmazás identitását?
• Ha az alkalmazás egy felhasználó nevében hívja meg az API-t, mi a felhasználó identitása?

Tulajdonosi jogkivonat

Az alkalmazás meghívásnál a fejlécbe állított hordozó token az alkalmazás identitásával kapcsolatos információkat tárolja. Emellett információkat is tárol a felhasználóról, kivéve, ha a webalkalmazás nem fogad szolgáltatásközi hívásokat egy démonalkalmazásból.

Íme egy C#-kód példa, amely azt mutatja be, hogy egy ügyfél meghívja az API-t, miután jogkivonatot szerez be a Microsoft Authentication Library for .NET -hez (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);

Fontos

Az ügyfélalkalmazás hozzáférési tokent kér a Microsoft Identitásplatformtól a webes API számára. Az API az egyetlen alkalmazás, amely ellenőriznie kell a jogkivonatot, és meg kell tekintenie a benne található jogcímeket. Az ügyfélalkalmazások soha ne próbáljanak jogkivonatokban megvizsgálni a jogcímeket.

A jövőben a webes API-nak szüksége lehet a jogkivonat titkosítására. Ez a követelmény megakadályozza a hozzáférési jogkivonatokat megtekintő ügyfélalkalmazások hozzáférését.

JwtBearer-konfiguráció

Ez a szakasz ismerteti, hogyan lehet konfigurálni egy hordozó tokent.

Konfigurációs fájl

Csak akkor kell megadnia a TenantId hozzáférési jogkivonatokat, ha egyetlen bérlőből (üzletági alkalmazásból) szeretné elfogadni a hozzáférési jogkivonatokat. Ellenkező esetben a fájl a következőképpen maradhat: common. A különböző értékek lehetnek:

• GUID (bérlőazonosító = címtárazonosító)
• common lehet bármilyen szervezeti és személyes fiók
• organizations bármely szervezet lehet
• consumers Személyes Microsoft-fiókok

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Egyéni alkalmazásazonosító URI használata webes API-hoz

Ha elfogadta az Azure Portal által javasolt alapértelmezett alkalmazásazonosító URI-t, nem kell megadnia a célközönséget. Ellenkező esetben adjon hozzá egy Audience tulajdonságot, amelynek értéke a webes API alkalmazásazonosítójának URI-ja. Ez általában a következővel api://kezdődik: .

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

Kód inicializálása

Amikor egy alkalmazás meghív egy olyan vezérlőműveletet, amely az [Authorize] attribútumot tartalmazza, az ASP.NET és ASP.NET Core kinyeri a hozzáférési jogkivonatot az Engedélyezési fejléc bearer tokenjéből. A hozzáférési jogkivonat ezután a JwtBearer köztes szoftverbe kerül, amely a Microsoft IdentityModel Extensions for .NET-et hívja meg.

Microsoft.Identity.Web

ASP.NET Core

A Microsoft azt javasolja, hogy használja a Microsoft.Identity.Web NuGet-csomagot, amikor webes API-t fejleszt ASP.NET Core-nal.

A Microsoft.Identity.Web biztosítja a kapcsolatot a ASP.NET Core, a hitelesítési köztes szoftver és a .NET-hez készült Microsoft Authentication Library (MSAL) között. Egyértelműbb, robusztusabb fejlesztői élményt tesz lehetővé, és kihasználja a Microsoft Identitásplatform és az Azure AD B2C előnyeit.

ASP.NET a .NET 6.0-hoz

A Microsoft.Identity.Web alkalmazást használó új webes API-projekt létrehozásához használjon egy projektsablont a .NET 6.0 CLI-ben vagy a Visual Studióban.

Dotnet core CLI

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

Visual Studio – Ha webes API-projektet szeretne létrehozni a Visual Studióban, válassza a > lehetőséget.

A .NET CLI és a Visual Studio projektsablonjai is létrehoznak egy Program.cs fájlt, amely a kódrészlethez hasonlóan néz ki. Vegye észre a Microsoft.Identity.Web "using" direktívát, valamint a hitelesítést és engedélyezést tartalmazó sorokat.

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

ASP.NET

A Microsoft azt javasolja, hogy használja a Microsoft.Identity.Web.OWIN NuGet-csomagot, amikor webes API-t fejleszt ASP.NET.

A Microsoft.Identity.Web.OWIN biztosítja a kapcsolatot a ASP.NET, a ASP.NET hitelesítési köztes szoftver és a .NET-hez készült Microsoft Authentication Library (MSAL) között. Egyértelműbb, robusztusabb fejlesztői élményt tesz lehetővé, és kihasználja a Microsoft Identitásplatform és az Azure AD B2C előnyeit.

Ugyanazt a konfigurációs fájlt használja, mint a ASP.NET Core (appsettings.json), és győződjön meg arról, hogy a fájl a projekt kimenetével van átmásolva (a tulajdonság másolása mindig a Visual Studio fájltulajdonságaiban vagy a .csprojban)

A Microsoft.Identity.Web.OWIN egy bővítmény metódust ad hozzá az AddMicrosoftIdentityWebApi nevű IAppBuilder-hez. Ez a módszer paraméterként egy olyan példányt OwinTokenAcquirerFactory vesz fel, amelyet meghív OwinTokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>() , és amely egy olyan példányt IServiceCollection jelenít meg, amelyhez számos szolgáltatást adhat hozzá az alsóbb rétegbeli API-k meghívásához vagy a tokengyorsítótár konfigurálásához.

Íme néhány mintakód a Startup.Auth.cs. A teljes kód elérhető a tests/DevApps/aspnet-mvc/OwinWebApp webhelyen

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

--

Token érvényesítés

Az előző kódrészletben a JwtBearer middleware, hasonlóan a webalkalmazásokban található OpenID Connect middleware-hez, a token a TokenValidationParameters értéke alapján érvényesíti. A tokent szükség szerint visszafejtik, a jogcímeket kinyerik, és az aláírást ellenőrzik. A köztes szoftver ezután ellenőrzi a jogkivonatot az adatok ellenőrzésével:

• Célközönség: A token a webes API-hoz van szánva.
• Sub: Egy olyan alkalmazáshoz lett kiadva, amely meghívhatja a webes API-t.
• Kiállító: Egy megbízható biztonsági token szolgáltatás (STS) adta ki.
• Lejárat: Élettartama tartományon belül van.
• Aláírás: Nem módosították.

Lehetnek speciális érvényesítések is. Ellenőrizheti például, hogy a jogkivonatba ágyazott aláíró kulcsok megbízhatók-e, és hogy a jogkivonat nem lesz-e újra lejátszva. Végül egyes protokollok konkrét ellenőrzést igényelnek.

Érvényesítők

Az érvényesítési lépéseket az érvényesítők rögzítik, amelyeket a Microsoft IdentityModel Extensions for .NET nyílt forráskódú könyvtára biztosít. Az érvényesítők a Microsoft.IdentityModel.Tokens/Validators.cs kódtár forrásfájljában vannak definiálva.

Ez a táblázat az érvényesítőket ismerteti:

Érvényesítő	Leírás
ÉrvényesítseKözönség	Biztosítja, hogy a jogkivonat annak az alkalmazásnak legyen, amely érvényesíti a jogkivonatot.
ÉrvényesítseIssuer	Biztosítja, hogy a jogkivonatot egy megbízható STS adta ki, ami azt jelenti, hogy egy megbízható személytől származik.
Hitelesítse a Kiadó Aláíró Kulcsát	Biztosítja, hogy a jogkivonatot érvényesítő alkalmazás megbízik a jogkivonat aláírásához használt kulcsban. Létezik egy speciális eset, amelyben a kulcs a jogkivonatba van beágyazva. De ez az eset általában nem merül fel.
ÉrvényesítésÉlettartam	Biztosítja, hogy a jogkivonat még mindig vagy már érvényes legyen. Az érvényesítő ellenőrzi, hogy a jogkivonat élettartama a notbefore és expires jogcímek által meghatározott tartományba esik-e.
Aláírás érvényesítése	Biztosítja, hogy a token ne legyen manipulálva.
ValidateTokenReplay	Gondoskodik arról, hogy a tokent ne lehessen újra felhasználni. Van egy speciális eset néhány egyszeri használatú protokollhoz.

Token-ellenőrzés testreszabása

Az érvényesítők a TokenValidationParameters osztály tulajdonságaihoz vannak társítva. Az ASP.NET és ASP.NET Core-konfigurációból inicializálódnak a tulajdonságok.

A legtöbb esetben nem kell módosítania a paramétereket. Azok az alkalmazások, amelyek nem önálló bérlők, kivételek. Ezek a webalkalmazások bármely szervezetből vagy személyes Microsoft-fiókból fogadnak felhasználókat. Ebben az esetben a kiállítókat ellenőrizni kell. A Microsoft.Identity.Web gondoskodik a kiállító érvényesítéséről is.

A ASP.NET Core-ban, ha testre szeretné szabni a jogkivonat-érvényesítési paramétereket, használja a következő kódrészletet a Startup.cs:

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

Az ASP.NET MVC esetében az alábbi kódminta bemutatja, hogyan végezhet egyéni jogkivonat-ellenőrzést:

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

Jogkivonat érvényesítése az Azure Functionsben

A bejövő hozzáférési jogkivonatokat az Azure Functionsben is ellenőrizheti. Az ilyen ellenőrzésre példákat az alábbi kódmintákban talál a GitHubon:

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

Következő lépések

Lépjen tovább a következő cikkre ebben a forgatókönyvben: Hatókörök és alkalmazásszerepkörök ellenőrzése a kódban.