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

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

• Aplikace jménem uživatelů, kteří mají správné obory a role.
• Aplikace démona, 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 ověření tokenu ASP.NET a ASP.NET Core. Vaše rozhraní API musí ověřit, že se token použitý k volání rozhraní API požaduje s očekávanými deklaracemi identity. Tyto deklarace identity vyžadují zejména ověření:

• Obory , pokud je rozhraní API volána jménem uživatele.
• Role aplikace, 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 konkrétní obory. 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ěření oborů 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, budete muset:

• Použití AddMicrosoftIdentityWebApi v Startup.cs, jak je vidět v konfiguraci kódu
• nebo jinak přidejte ScopeAuthorizationRequirement zásady 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ěření globálnějších oborů

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 dokumentaci k ASP.NET Core autorizaci na základě deklarací identity.

Co je ověřené?

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

• Ověřte, že je deklarace identity 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 ValidateScopes ASP.NET Core najdete v tématu ScopesRequiredHttpContextExtensions.cs

Ověření rolí aplikací v rozhraních API volaných aplikacemi démona

Pokud vaše webové rozhraní API volá aplikace démona, 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é můžou také používat deklarace identity rolí ve vzorech přiřazení uživatelů, jak ukazuje postup přidání rolí aplikací do aplikace a jejich přijetí v tokenu. Pokud jsou role přiřazovatelné oběma, kontrola rolí umožní aplikacím přihlásit se jako uživatelé a uživatelé 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é deklarace identity rolí ověřit také v rozhraní 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ů jen pro aplikaci, pokud by webové rozhraní API mělo být volány pouze aplikacemi démona

Pokud chcete, aby webové rozhraní API volali jenom aplikace démona, přidejte podmínku, že token je token jen pro aplikaci, když ověříte 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 seznamu ACL

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 ASP.NET Core, budete muset deklarovat, že používáte autorizaci založenou na seznamu ACL, jinak web Microsoft Identity web vyvolá výjimku, pokud se v zadaných deklarací identity nezobrazí žádné role ani obory:

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

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

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

Pokud nastavíte AllowWebApiToBeAuthorizedByACL truenastavení , je to vaše odpovědnost za zajištění mechanismu seznamu ACL.

Další kroky

• Další informace o vytvoření webové aplikace ASP.NET Core, která přihlašuje uživatele v následující sérii kurzů s více částmi

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