Chráněné webové rozhraní API: Konfigurace kódu

Platí pro: Tenanti pracovních sil (další informace)

Pokud chcete nakonfigurovat kód pro chráněné webové rozhraní API, seznamte se s následujícími informacemi:

• Co definuje rozhraní API jako chráněná.
• Jak nakonfigurovat nosný token
• Postup ověření tokenu

Přijatá verze tokenu

Platforma Microsoft Identity Platform může vydávat tokeny v1.0 a tokeny v2.0. Další informace o těchto tokenech najdete v Přístupové tokeny.

Verze tokenu, kterou vaše rozhraní API může přijmout, závisí na výběru podporovaných typů účtů při vytváření registrace aplikace webového rozhraní API na webu Azure Portal.

• Pokud je hodnota podporovaných typů účtůÚčty v libovolném organizačním adresáři a osobních účtech Microsoft (například Skype, Xbox, Outlook.com), musí být verze přijatého tokenu verze 2.0.
• V opačném případě může být verze přijatého tokenu verze 1.0.

Po vytvoření aplikace můžete určit nebo změnit přijatou verzi tokenu pomocí následujícího postupu:

1. V Centru pro správu Microsoft Entra vyberte aplikaci a pak vyberte Manifest.
2. Vyhledejte vlastnost accessTokenAcceptedVersion v manifestu.
3. Hodnota určuje pro Microsoft Entra, kterou verzi tokenu přijímá webové API.
   • Pokud je hodnota 2, webové rozhraní API přijímá tokeny v2.0.
   • Pokud je hodnota null, webové rozhraní API přijímá tokeny v1.0.
4. Pokud jste změnili verzi tokenu, vyberte Uložit.

Webové rozhraní API určuje, jakou verzi tokenu přijímá. Když klient požádá o token pro webové rozhraní API z platformy Microsoft Identity Platform, klient získá token, který označuje verzi tokenu, kterou webové rozhraní API přijímá.

Co definuje ASP.NET a ASP.NET základní rozhraní API jako chráněná?

Podobně jako u webových aplikací jsou chráněná webová rozhraní API ASP.NET a ASP.NET Core, protože jejich akce kontroleru mají předponu atributu [Authorize]. Akce kontroleru je možné volat pouze v případě, že se rozhraní API volá s autorizovanou identitou.

Zvažte následující otázky:

• Webové rozhraní API může volat jenom aplikace. Jak rozhraní API zná identitu aplikace, která ji volá?
• Pokud aplikace volá rozhraní API jménem uživatele, jaká je identita uživatele?

Nosný token

Nosný token nastavený v hlavičce při zavolání aplikace obsahuje informace o identitě aplikace. Obsahuje také informace o uživateli, pokud webová aplikace nepřijímá volání mezi službami z aplikace démona.

Tady je příklad kódu jazyka C#, který zobrazuje klienta volajícího rozhraní API po získání tokenu s knihovnou Microsoft Authentication Library pro .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);

Důležité

Klientská aplikace požaduje nosný token na platformu Microsoft Identity Platform pro webové rozhraní API. Rozhraní API je jediná aplikace, která by měla token ověřit a zobrazit deklarace identity, které obsahuje. Klientské aplikace by se nikdy neměly pokoušet kontrolovat deklarace identity v tokenech.

V budoucnu může webové rozhraní API vyžadovat šifrování tokenu. Tento požadavek by zabránil přístupu klientským aplikacím, které můžou zobrazit přístupové tokeny.

Konfigurace JwtBearer

Tato část popisuje, jak nakonfigurovat nosný token.

Konfigurační soubor

Musíte zadat TenantId pouze v případě, že chcete přijímat přístupové tokeny z jednoho tenanta (obchodní aplikace). V opačném případě může být ponechán jako common. Různé hodnoty můžou být následující:

• IDENTIFIKÁTOR GUID (ID tenanta = ID adresáře)
• common může být jakýkoliv organizační a osobní účet.
• organizations může být libovolná organizace.
• consumers jsou osobní účty Microsoft.

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

Použití vlastního identifikátoru URI ID aplikace pro webové rozhraní API

Pokud jste přijali výchozí identifikátor URI ID aplikace navržený na webu Azure Portal, nemusíte zadávat cílovou skupinu. V opačném případě přidejte Audience vlastnost, jejíž hodnotou je identifikátor URI ID aplikace pro webové rozhraní API. Obvykle začíná na api://.

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

Inicializace kódu

Když je aplikace volána v akci kontroleru, která obsahuje atribut [Authorize], ASP.NET a ASP.NET Core extrahuje přístupový token z nosný token hlavičky autorizace. Přístupový token se pak předá do middlewaru JwtBearer, který volá rozšíření Microsoft IdentityModel pro .NET.

Microsoft.Identity.Web

ASP.NET Core

Microsoft doporučuje použít balíček NuGet Microsoft.Identity.Web při vývoji webového rozhraní API s ASP.NET Core.

Microsoft.Identity.Web poskytuje připevnění mezi ASP.NET Core, middlewarem ověřování a knihovnou MSAL (Microsoft Authentication Library) pro .NET. Umožňuje jasnější a robustnější vývojářské prostředí a využívá sílu platformy Microsoft Identity Platform a Azure AD B2C.

ASP.NET pro .NET 6.0

Pokud chcete vytvořit nový projekt webového rozhraní API, který používá Microsoft.Identity.Web, použijte šablonu projektu v rozhraní příkazového řádku .NET 6.0 nebo sadě Visual Studio.

Rozhraní příkazového řádku Dotnet Core

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

Visual Studio – Pokud chcete vytvořit projekt webového rozhraní API v sadě Visual Studio, vyberte >

Šablony projektů .NET CLI i sady Visual Studio vytvoří soubor Program.cs , který bude vypadat podobně jako tento fragment kódu. Všimněte si Microsoft.Identity.Web použití direktivy a řádků obsahujících ověřování a autorizaci.

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

Microsoft doporučuje použít balíček NuGet Microsoft.Identity.Web.OWIN při vývoji webového rozhraní API s ASP.NET.

Microsoft.Identity.Web.OWIN poskytuje připevnění mezi ASP.NET, middlewarem ověřování ASP.NET a knihovnou MSAL (Microsoft Authentication Library) pro .NET. Umožňuje jasnější a robustnější vývojářské prostředí a využívá sílu platformy Microsoft Identity Platform a Azure AD B2C.

Používá stejný konfigurační soubor jako ASP.NET Core (appsettings.json) a musíte se ujistit, že se tento soubor zkopíruje s výstupem projektu (vlastnost se vždy zkopíruje ve vlastnostech souboru v sadě Visual Studio nebo v souboru .csproj).

Microsoft.Identity.Web.OWIN přidá rozšiřující metody do IAppBuilder s názvem AddMicrosoftIdentityWebApi. Tato metoda přebírá jako parametr instanci OwinTokenAcquirerFactory , kterou získáte volání OwinTokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>() a která zobrazí instanci IServiceCollection , do které můžete přidat mnoho služeb pro volání podřízených rozhraní API nebo nakonfigurovat mezipaměť tokenů.

Tady je ukázkový kód pro Startup.Auth.cs. Úplný kód je k dispozici v testech/ 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();
        }
    }
}

--

Ověření tokenu

V předchozím fragmentu kódu ověřuje middleware JwtBearer, jako je middleware OpenID Connect ve webových aplikacích, token na základě hodnoty TokenValidationParameters. Token se podle potřeby dešifruje, deklarace identity se extrahují a podpis se ověří. Middleware pak token ověří kontrolou těchto dat:

• Cílová skupina: Token je určený pro webové rozhraní API.
• Sub: Byla vydána pro aplikaci, která může volat webové rozhraní API.
• Vystavitel: Byla vydána důvěryhodnou službou tokenů zabezpečení (STS).
• Platnost vypršela: Jeho životnost je v rozsahu.
• Podpis: Nebylo s ním manipulováno.

Můžou existovat také speciální ověření. Je například možné ověřit, že podpisové klíče, když jsou vložené do tokenu, důvěryhodné a že se token nepřehrává. A konečně některé protokoly vyžadují konkrétní ověření.

Validátory

Ověřovací kroky se zaznamenávají v validátorech, které poskytuje open source knihovna Microsoft IdentityModel Extensions pro .NET . Validátory jsou definovány ve zdrojovém souboru knihovny Microsoft.IdentityModel.Tokens/Validators.cs.

Tato tabulka popisuje validátory:

Validátor	Popis
Ověřit cílové publikum	Zajišťuje, že token je určený pro aplikaci, která token ověří za vás.
ValidateIssuer (Ověřit)	Zajišťuje, že token vydal důvěryhodný stS, což znamená, že je od někoho, komu důvěřujete.
Ověřit Klíč k Podepsání Vydavatele	Zajišťuje, že aplikace ověřující token důvěřuje klíči použitému k podepsání tokenu. Existuje zvláštní případ, kdy je klíč vložený do tokenu. Ale tento případ obvykle nevypadá.
ValidateLifetime	Zajišťuje, že token je stále nebo již platný. Validátor zkontroluje, jestli je životnost tokenu v rozsahu určeném notbefore a vyprší platnost deklarací identity.
ValidateSignature	Zajišťuje, že token nebyl manipulován.
ValidateTokenReplay	Zajišťuje, že se token nepřehraje. U některých jednorázových protokolů existuje zvláštní případ.

Přizpůsobení ověření tokenu

Validátory jsou přidruženy vlastnosti TokenValidationParameters třídy. Vlastnosti se inicializují z konfigurace ASP.NET a ASP.NET Core.

Ve většině případů nemusíte měnit parametry. Aplikace, které nejsou jedním tenantem, jsou výjimkami. Tyto webové aplikace přijímají uživatele z libovolné organizace nebo z osobních účtů Microsoft. V tomto případě musí být ověřeni vystavitely. Microsoft.Identity.Web se postará také o ověření vystavitele.

Pokud chcete v ASP.NET Core přizpůsobit parametry ověření tokenu, použijte ve svém Startup.cs následující fragment kódu:

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

Následující ukázka kódu pro ASP.NET MVC ukazuje, jak provést ověření vlastního tokenu:

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

Ověřování tokenů ve službě Azure Functions

Můžete také ověřit příchozí přístupové tokeny ve službě Azure Functions. Příklady takového ověření najdete v následujících ukázkách kódu na GitHubu:

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

Další kroky

Přejděte k dalšímu článku v tomto scénáři a ověřte obory a role aplikací v kódu.