Chráněné webové rozhraní API: Ověření oborů a rolí aplikací

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

Tento článek popisuje, jak můžete do webového rozhraní API přidat autorizaci. Tato ochrana zajišťuje, že API bude voláno pouze následujícími subjekty:

• Aplikace jménem uživatelů, kteří mají správná oprávnění a role.
• Aplikace démon, které mají správné role aplikací.

Fragmenty kódu v tomto článku se extrahují z následujících ukázek kódu na GitHubu:

• Inkrementální kurz k webovému rozhraní API ASP.NET Core
• Ukázka webového rozhraní API ASP.NET

Pokud chcete chránit webové rozhraní API ASP.NET nebo ASP.NET Core, musíte přidat [Authorize] atribut do jedné z následujících položek:

• Samotný kontroler, pokud chcete, aby byly všechny akce kontroleru chráněné
• Akce jednotlivého kontroleru pro vaše rozhraní API

    [Authorize]
    public class TodoListController : Controller
    {
     // ...
    }

Ale tato ochrana nestačí. Zaručuje pouze, že ASP.NET a ASP.NET Core ověří token. Vaše rozhraní API musí ověřit, že se token použitý k volání rozhraní API požaduje s očekávanými nároky. Tyto deklarace identity vyžadují zejména ověření:

• Rozsahy , pokud je rozhraní API voláno jménem uživatele.
• Role aplikace, které lze použít, pokud je možné rozhraní API volat z aplikace démona.

Ověření oborů v rozhraních API volaných jménem uživatelů

Pokud klientská aplikace volá vaše rozhraní API jménem uživatele, musí rozhraní API požádat o nosný token, který má pro rozhraní API specifické rozsahy. Další informace naleznete v tématu Konfigurace kódu | Nosný token.

ASP.NET Core

V ASP.NET Core můžete pomocí Microsoft.Identity.Web ověřit obory v každé akci kontroleru. Můžete je také ověřit na úrovni kontroleru nebo pro celou aplikaci.

Ověřte rozsahy jednotlivých akcí kontroleru.

Obory v akci kontroleru můžete ověřit pomocí atributu [RequiredScope] . Tento atribut má několik přepsání. Ten, který přebírá požadované obory přímo, a ten, který přebírá klíč ke konfiguraci.

Ověření oborů v akci kontroleru s pevně zakódovanými obory

Následující fragment kódu ukazuje použití atributu [RequiredScope] s pevně zakódovanými obory.

using Microsoft.Identity.Web

[Authorize]
public class TodoListController : Controller
{
    /// <summary>
    /// The web API will accept only tokens that have the `access_as_user` scope for
    /// this API.
    /// </summary>
    const string scopeRequiredByApi = "access_as_user";

    // GET: api/values
    [HttpGet]
    [RequiredScope(scopeRequiredByApi)]
    public IEnumerable<TodoItem> Get()
    {
        // Do the work and return the result.
        // ...
    }
 // ...
}

Ověření oborů v akci kontroleru s obory definovanými v konfiguraci

Můžete také deklarovat tyto požadované obory v konfiguraci a odkazovat na konfigurační klíč:

Pokud například v appsettings.json máte následující konfiguraci:

{
 "AzureAd" : {
   // more settings
   "Scopes" : "access_as_user access_as_admin"
  }
}

Pak na něj v atributu [RequiredScope] odkazujte:

using Microsoft.Identity.Web

[Authorize]
public class TodoListController : Controller
{
    // GET: api/values
    [HttpGet]
    [RequiredScope(RequiredScopesConfigurationKey = "AzureAd:Scopes")]
    public IEnumerable<TodoItem> Get()
    {
        // Do the work and return the result.
        // ...
    }
 // ...
}

Podmíněně ověřit obory

Existují případy, kdy chcete podmíněně ověřit obory. Můžete to provést pomocí VerifyUserHasAnyAcceptedScope metody rozšíření v souboru HttpContext.

using Microsoft.Identity.Web

[Authorize]
public class TodoListController : Controller
{
    /// <summary>
    /// The web API will accept only tokens 1) for users, 2) that have the `access_as_user` scope for
    /// this API.
    /// </summary>
    static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

    // GET: api/values
    [HttpGet]
    public IEnumerable<TodoItem> Get()
    {
         HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);
        // Do the work and return the result.
        // ...
    }
 // ...
}

Ověřte rozsahy na úrovni kontroleru.

Můžete také ověřit rozsahy pro celý kontroler.

Ověřte obory na řadiči s pevně zakódovanými obory

Následující fragment kódu ukazuje použití atributu [RequiredScope] s pevně zakódovanými obory na kontroleru. Pokud chcete použít RequiredScopeAttribute, musíte provést jednu z těchto akcí:

• Použití AddMicrosoftIdentityWebApi v Startup.cs, jak je vidět v konfiguraci kódu
• nebo jinak přidejte ScopeAuthorizationRequirement k zásadám autorizace, jak je vysvětleno v zásadách autorizace.

using Microsoft.Identity.Web

[Authorize]
[RequiredScope(scopeRequiredByApi)]
public class TodoListController : Controller
{
    /// <summary>
    /// The web API will accept only tokens 1) for users, 2) that have the `access_as_user` scope for
    /// this API.
    /// </summary>
    static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

    // GET: api/values
    [HttpGet]
    public IEnumerable<TodoItem> Get()
    {
        // Do the work and return the result.
        // ...
    }
 // ...
}

Ověření oborů na kontroleru s obory definovanými v konfiguraci

Podobně jako u akce můžete také deklarovat tyto požadované obory v konfiguraci a odkazovat na konfigurační klíč:

using Microsoft.Identity.Web

[Authorize]
[RequiredScope(RequiredScopesConfigurationKey = "AzureAd:Scopes")]
public class TodoListController : Controller
{
    // GET: api/values
    [HttpGet]
    public IEnumerable<TodoItem> Get()
    {
        // Do the work and return the result.
        // ...
    }
 // ...
}

Ověřte rozsahy globálněji

Doporučeným přístupem je definování podrobných rozsahů pro webové rozhraní API a ověření rozsahů v jednotlivých akcích kontroleru. Je ale také možné ověřit rozsahy na úrovni aplikace nebo kontroleru. Podrobnosti najdete v části autorizace založená na deklaracích v dokumentaci k ASP.NET Core.

Co je ověřené?

Atribut [RequiredScope] a VerifyUserHasAnyAcceptedScope metoda, dělá něco jako následující kroky:

• Ověřte, zda existuje nárok pojmenovaný http://schemas.microsoft.com/identity/claims/scope nebo scp.
• Ověřte, že deklarace identity obsahuje hodnotu, která obsahuje obor očekávaný rozhraním API.

ASP.NET Classic

V aplikaci ASP.NET můžete obory ověřit následujícím způsobem:

[Authorize]
public class TodoListController : ApiController
{
    public IEnumerable<TodoItem> Get()
    {
       ValidateScopes(new[] {"read"; "admin" } );
       // ...
    }

Níže je zjednodušená verze ValidateScopes:

private void ValidateScopes(IEnumerable<string> acceptedScopes)
{
    //
    // The `role` claim tells you what permissions the client application has in the service.
    // In this case, we look for a `role` value of `access_as_application`.
    //
    Claim scopeClaim = ClaimsPrincipal.Current.FindFirst("scp");
    if (scopeClaim == null || !scopeClaim.Value.Split(' ').Intersect(acceptedScopes).Any())
    {
        throw new HttpResponseException(new HttpResponseMessage
        { StatusCode = HttpStatusCode.Forbidden,
            ReasonPhrase = $"The 'scp' claim does not contain '{scopeClaim}' or was not found"
        });
    }
}

Úplnou verzi pro ASP.NET Core viz ScopesRequiredHttpContextExtensions.cs

Ověření rolí aplikací v API volaných démonovými aplikacemi

Pokud vaše webové rozhraní API volá démonová aplikace, měla by tato aplikace vyžadovat oprávnění aplikace k vašemu webovému rozhraní API. Jak je znázorněno v zobrazení oprávnění aplikace (role aplikací), vaše rozhraní API taková oprávnění zveřejňuje. Jedním z příkladů je access_as_application role aplikace.

Teď potřebujete, aby vaše rozhraní API ověřilo, že token, který přijímá, obsahuje roles deklaraci identity a že tato deklarace identity má očekávanou hodnotu. Ověřovací kód se podobá kódu, který ověřuje delegovaná oprávnění, s tím rozdílem, že akce kontroleru testují role místo oborů:

ASP.NET Core

Následující fragment kódu ukazuje, jak ověřit roli aplikace;

using Microsoft.Identity.Web

[Authorize]
public class TodoListController : ApiController
{
    public IEnumerable<TodoItem> Get()
    {
        HttpContext.ValidateAppRole("access_as_application");
        // ...
    }

Místo toho můžete použít [Authorize(Roles = "access_as_application")] atributy na kontroleru nebo akci (nebo stránku razor Page).

[Authorize(Roles = "access_as_application")]
MyController : ApiController
{
    // ...
}

Autorizace založená na rolích v ASP.NET Core obsahuje několik přístupů k implementaci autorizace na základě rolí. Vývojáři si můžou vybrat jednu z nich, která vyhovuje jejich příslušným scénářům.

Pracovní ukázky najdete v přírůstkovém kurzu webové aplikace o autorizaci podle rolí a skupin.

ASP.NET Classic

V aplikaci ASP.NET můžete role aplikací ověřit následujícím způsobem:

[Authorize]
public class TodoListController : ApiController
{
    public IEnumerable<TodoItem> Get()
    {
       ValidateAppRole("access_as_application");
       // ...
    }

Zjednodušená verze ValidateAppRole je:

private void ValidateAppRole(string appRole)
{
    //
    // The `role` claim tells you what permissions the client application has in the service.
    // In this case, we look for a `role` value of `access_as_application`.
    //
    Claim roleClaim = ClaimsPrincipal.Current.FindFirst("roles");
    if (roleClaim == null || !roleClaim.Value.Split(' ').Contains(appRole))
    {
        throw new HttpResponseException(new HttpResponseMessage
        { StatusCode = HttpStatusCode.Unauthorized,
            ReasonPhrase = $"The 'roles' claim does not contain '{appRole}' or was not found"
        });
    }
}

Úplnou verzi ValidateAppRole ASP.NET Core najdete v RolesRequiredHttpContextExtensions.cs kódu.

Ověření rolí aplikací v rozhraních API volaných jménem uživatelů

Uživatelé mohou také používat deklarace rolí ve vzorech přiřazení uživatelů, jak ukazuje postup přidání rolí do aplikací a jejich získání v tokenu. Pokud jsou role přiřazovatelné oběma, kontrola rolí umožní, aby se aplikace mohly přihlásit jako uživatelé a uživatelé mohli přihlásit jako aplikace. Doporučujeme deklarovat různé role pro uživatele a aplikace, abyste zabránili tomuto nejasnostem.

Pokud jste definovali role aplikací s uživatelem nebo skupinou, je možné nárok na role ověřit také v API spolu s obory. Logika ověřování rolí aplikace v tomto scénáři zůstává stejná, jako kdyby rozhraní API volala aplikace démona, protože deklarace identity role pro uživatele nebo skupinu a aplikaci není nijak diferencovaná.

Přijetí tokenů pouze pro aplikace, pokud by webové rozhraní API mělo být voláno pouze aplikacemi démona

Pokud chcete, aby vaše webové rozhraní API volaly pouze démonové aplikace, přidejte podmínku, že token je pouze pro aplikaci, když ověřujete roli aplikace.

string oid = ClaimsPrincipal.Current.FindFirst("oid")?.Value;
string sub = ClaimsPrincipal.Current.FindFirst("sub")?.Value;
bool isAppOnly = oid != null && sub != null && oid == sub;

Kontrola inverzní podmínky umožňuje volání rozhraní API jenom aplikacím, které se přihlašují uživatelem.

Použití autorizace založené na ACL (seznam řízení přístupu)

Alternativně k autorizaci na základě aplikačních rolí můžete webové rozhraní API chránit pomocí autorizačního vzoru založeného na seznamu řízení přístupu (ACL) a řídit tokeny bez roles deklarace identity.

Pokud používáte Microsoft.Identity.Web na ASP.NET Core, musíte deklarovat, že používáte autorizaci založenou na ACL, jinak Microsoft Identity Web vyvolá výjimku, pokud nejsou v zadaných nárocích uvedeny ani role, ani rozsahy.

System.UnauthorizedAccessException: IDW10201: Neither scope or roles claim was found in the bearer token.

Chcete-li se této výjimce vyhnout, nastavte vlastnost konfigurace AllowWebApiToBeAuthorizedByACL na true v souboru appsettings.json nebo programově.

{
 "AzureAD"
 {
  // other properties
  "AllowWebApiToBeAuthorizedByACL" : true,
  // other properties
 }
}

Pokud nastavíte AllowWebApiToBeAuthorizedByACL na true, je vaší odpovědností zajistit mechanismus řízení přístupu (ACL).

Další kroky

• Další informace získáte vytvořením webové aplikace ASP.NET Core, která přihlašuje uživatele v následující vícedílné sérii kurzů

• Prozkoumání ukázek webového rozhraní API platformy Microsoft Identity Platform