Védett webes API: Hatókörök és alkalmazásszerepkörök ellenőrzése

Ez a cikk bemutatja, hogyan adhat hozzá engedélyezést a webes API-hoz. Ez a védelem biztosítja, hogy az API-t csak a következők hívják meg:

• Alkalmazások a megfelelő hatókörrel és szerepkörrel rendelkező felhasználók nevében.
• A megfelelő alkalmazásszerepköröket használó démonalkalmazások.

A cikkben szereplő kódrészleteket a gitHubon található alábbi kódmintákból nyerjük ki:

• ASP.NET Core webes API növekményes oktatóanyaga
• ASP.NET webes API-minta

Egy ASP.NET vagy ASP.NET Core webes API védelméhez hozzá kell adnia az [Authorize] attribútumot az alábbi elemek egyikéhez:

• Maga a vezérlő, ha azt szeretné, hogy minden vezérlőművelet védve legyen
• Az API egyéni vezérlőművelete

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

De ez a védelem nem elég. Csak azt garantálja, hogy ASP.NET és ASP.NET Core érvényesítse a jogkivonatot. Az API-nak ellenőriznie kell, hogy az API meghívásához használt jogkivonatot a várt jogcímekkel kéri-e a rendszer. Ezek a jogcímek különösen ellenőrzésre szorulnak:

• A hatókörök, ha az API-t egy felhasználó nevében hívják meg.
• Az alkalmazásszerepkörök , ha az API meghívható egy démonalkalmazásból.

Hatókörök ellenőrzése a felhasználók nevében meghívott API-kban

Ha egy ügyfélalkalmazás egy felhasználó nevében hívja meg az API-t, az API-nak egy tulajdonosi jogkivonatot kell kérnie, amely meghatározott hatókörrel rendelkezik az API-hoz. További információ: Kódkonfiguráció | Tulajdonosi jogkivonat.

ASP.NET Core

A ASP.NET Core-ban a Microsoft.Identity.Web használatával ellenőrizheti a hatóköröket az egyes vezérlőműveletekben. Ezeket a vezérlő szintjén vagy a teljes alkalmazás esetében is ellenőrizheti.

Ellenőrizze a hatóköröket az egyes vezérlőműveleteken

A vezérlőművelet hatóköreit az [RequiredScope] attribútum használatával ellenőrizheti. Ez az attribútum több felülbírálást is rendelkezik. Az egyik, amely közvetlenül a szükséges hatóköröket veszi át, a másik pedig a konfiguráció kulcsát.

Vezérlőművelet hatóköreinek ellenőrzése rögzített hatókörökkel

Az alábbi kódrészlet a rögzített hatókörökkel rendelkező attribútum használatát [RequiredScope] mutatja be.

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.
        // ...
    }
 // ...
}

Vezérlőművelet hatóköreinek ellenőrzése a konfigurációban meghatározott hatókörökkel

Deklarálhatja ezeket a szükséges hatóköröket a konfigurációban, és hivatkozhat a konfigurációs kulcsra:

Ha például appsettings.json a következő konfigurációval rendelkezik:

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

Ezután hivatkozzon rá az [RequiredScope] attribútumban:

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.
        // ...
    }
 // ...
}

Hatókörök feltételes ellenőrzése

Vannak olyan esetek, amikor feltételesen szeretné ellenőrizni a hatóköröket. Ezt a VerifyUserHasAnyAcceptedScope bővítménymetódussal teheti meg a HttpContextkövetkezőn: .

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.
        // ...
    }
 // ...
}

A hatókörök ellenőrzése a vezérlő szintjén

A teljes vezérlő hatóköreit is ellenőrizheti

A vezérlő hatóköreinek ellenőrzése rögzített hatókörökkel

Az alábbi kódrészlet az attribútum használatát [RequiredScope] mutatja be a vezérlőben rögzített hatókörökkel. A RequiredScopeAttribute használatához a következőkre lesz szüksége:

• Használat AddMicrosoftIdentityWebApi a Startup.cs, ahogy a Kód konfigurációja is szemlélteti
• vagy más módon adja hozzá az ScopeAuthorizationRequirement engedélyezési szabályzathoz az engedélyezési szabályzatokban leírtak szerint.

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.
        // ...
    }
 // ...
}

A vezérlő hatóköreinek ellenőrzése a konfigurációban meghatározott hatókörökkel

A művelethez hasonlóan a konfigurációban is deklarálhatja ezeket a szükséges hatóköröket, és hivatkozhat a konfigurációs kulcsra:

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.
        // ...
    }
 // ...
}

A hatókörök globálisabb ellenőrzése

A webes API részletes hatóköreinek meghatározása és a hatókörök ellenőrzése az egyes vezérlőműveletekben az ajánlott módszer. A hatóköröket azonban az alkalmazás vagy a vezérlő szintjén is ellenőrizheti. További részletekért tekintse meg a jogcímalapú engedélyezést a ASP.NET Core dokumentációjában.

Mi van ellenőrizve?

Az [RequiredScope] attribútum és VerifyUserHasAnyAcceptedScope a metódus a következő lépésekhez hasonlóan működik:

• Ellenőrizze, hogy van-e elnevezett http://schemas.microsoft.com/identity/claims/scope jogcím vagy scp.
• Ellenőrizze, hogy a jogcím rendelkezik-e olyan értékkel, amely tartalmazza az API által várt hatókört.

ASP.NET klasszikus

Egy ASP.NET alkalmazásban a hatóköröket a következő módon ellenőrizheti:

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

Az alábbiakban a következő egyszerűsített verziója látható 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"
        });
    }
}

A ASP.NET Core teljes verziójáért ValidateScopes tekintse meg a ScopesRequiredHttpContextExtensions.cs

Alkalmazásszerepkörök ellenőrzése démonalkalmazások által hívott API-kban

Ha a webes API-t démonalkalmazás hívja meg, az alkalmazásnak alkalmazásengedélyt kell kérnie a webes API-hoz. Ahogy az alkalmazásengedélyek (alkalmazásszerepkörök) közzétételekor látható, az API közzéteszi az ilyen engedélyeket. Ilyen például az access_as_application alkalmazásszerepkör.

Most meg kell győződnie arról, hogy az API-nak ellenőriznie kell, hogy a kapott jogkivonat tartalmazza-e a roles jogcímet, és hogy ez a jogcím rendelkezik-e a várt értékkel. Az ellenőrző kód hasonló ahhoz a kódhoz, amely ellenőrzi a delegált engedélyeket, azzal a kivételrel, hogy a vezérlő a hatókörök helyett a szerepköröket teszteli:

ASP.NET Core

Az alábbi kódrészlet bemutatja, hogyan ellenőrizheti az alkalmazásszerepkört;

using Microsoft.Identity.Web

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

Ehelyett használhatja a [Authorize(Roles = "access_as_application")] vezérlő attribútumait vagy egy műveletet (vagy egy borotvalapot).

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

A szerepköralapú engedélyezés a ASP.NET Core-ban számos módszert sorol fel a szerepköralapú engedélyezés implementálásához. A fejlesztők választhatnak közülük, amely megfelel a saját forgatókönyvüknek.

A munkamintákat a webalkalmazás szerepkörök és csoportok általi engedélyezéséről szóló növekményes oktatóanyagban tekintheti meg.

ASP.NET klasszikus

Egy ASP.NET alkalmazásban az alábbi módon ellenőrizheti az alkalmazásszerepköröket:

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

Az egyszerűsített verzió a ValidateAppRole következő:

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

A ASP.NET Core teljes verziójáért ValidateAppRole tekintse meg RolesRequiredHttpContextExtensions.cs kódot.

Alkalmazásszerepkörök ellenőrzése a felhasználók nevében meghívott API-kban

A felhasználók szerepkör-jogcímeket is használhatnak a felhasználói hozzárendelési mintákban, ahogyan az alkalmazásszerepkörök hozzáadása és fogadása a jogkivonatban látható. Ha a szerepkörök mindkettőhöz hozzárendelhetők, a szerepkörök ellenőrzése lehetővé teszi, hogy az alkalmazások felhasználókként és felhasználókként jelentkezzenek be alkalmazásként. Javasoljuk, hogy a félreértés elkerülése érdekében deklaráljon különböző szerepköröket a felhasználók és az alkalmazások számára.

Ha felhasználóval/csoporttal definiált alkalmazásszerepköröket, akkor a szerepkör-jogcím az API-ban is ellenőrizhető a hatókörökkel együtt. Ebben a forgatókönyvben az alkalmazásszerepkörök ellenőrzési logikája ugyanaz marad, mintha a démonalkalmazások meghívják volna az API-t, mivel a felhasználó/csoport és alkalmazás szerepkör-jogcímében nincs különbség.

Csak alkalmazásjogkivonatok elfogadása, ha a webes API-t csak démonalkalmazások hívhatják meg

Ha azt szeretné, hogy csak a démonalkalmazások hívják meg a webes API-t, adja hozzá azt a feltételt, hogy a jogkivonat csak alkalmazás-jogkivonat legyen az alkalmazásszerepkör érvényesítésekor.

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

Az inverz feltétel ellenőrzése csak a felhasználót bejelentkező alkalmazások számára teszi lehetővé az API meghívását.

ACL-alapú engedélyezés használata

Az alkalmazásszerepköröken alapuló engedélyezés mellett a webes API-t hozzáférés-vezérlési lista (ACL) alapú engedélyezési mintával is megvédheti, hogy jogcím nélkül vezérelje a roles jogkivonatokat.

Ha ASP.NET Core-t használ Microsoft.Identity.Web , deklarálnia kell, hogy ACL-alapú hitelesítést használ, ellenkező esetben a Microsoft Identity Web kivételt jelez, ha sem a szerepkörök, sem a hatókörök nem szerepelnek a megadott jogcímekben:

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

A kivétel elkerülése érdekében állítsa a AllowWebApiToBeAuthorizedByACL konfigurációs tulajdonságot true appsettings.json vagy programozott módon.

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

Ha ezt állítja truebeAllowWebApiToBeAuthorizedByACL, ez az Ön felelőssége az ACL-mechanizmus biztosítása érdekében.

Következő lépések

• További információ egy ASP.NET Core-webalkalmazás létrehozásával, amely bejelentkezik a felhasználókba az alábbi többrészes oktatóanyag-sorozatban

• Microsoft Identitásplatform webes API-minták felfedezése