Beveiligde web-API: bereiken en app-rollen controleren

In dit artikel wordt beschreven hoe u autorisatie kunt toevoegen aan uw web-API. Deze beveiliging zorgt ervoor dat de API alleen wordt aangeroepen door:

• Toepassingen namens gebruikers met de juiste bereiken en rollen.
• Daemon-apps met de juiste toepassingsrollen.

De codefragmenten in dit artikel worden geëxtraheerd uit de volgende codevoorbeelden op GitHub:

• Stapsgewijze zelfstudie voor de ASP.NET Core web-API
• Voorbeeld van ASP.NET web-API

Als u een ASP.NET of ASP.NET Core web-API wilt beveiligen, moet u het kenmerk [Authorize] toevoegen aan een van de volgende items:

• De controller zelf als u wilt dat alle controlleracties worden beveiligd
• De afzonderlijke controlleractie voor uw API

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

Maar deze bescherming is niet voldoende. Dit garandeert alleen dat ASP.NET en ASP.NET Core het token valideren. Uw API moet controleren of het token dat wordt gebruikt om de API aan te roepen, wordt aangevraagd met de verwachte claims. Deze claims hebben met name verificatie nodig voor het volgende:

• De bereiken als de API wordt aangeroepen namens een gebruiker.
• De app-rollen als de API kan worden aangeroepen vanuit een daemon-app.

Bereiken verifiëren in API's die namens gebruikers worden aangeroepen

Als een client-app uw API aanroept namens een gebruiker, moet de API een bearer-token aanvragen dat specifieke bereiken voor de API heeft. Zie Codeconfiguratie | Bearer-token voor meer informatie.

ASP.NET Core

In ASP.NET Core kunt u Microsoft.Identity.Web gebruiken om bereiken in elke controlleractie te verifiëren. U kunt ze ook verifiëren op het niveau van de controller of voor de hele toepassing.

De bereiken voor elke controlleractie verifiëren

U kunt de bereiken in de controlleractie verifiëren met behulp van het kenmerk [RequiredScope]. Dit kenmerk heeft verschillende onderdrukkingen. Een die de vereiste bereiken rechtstreeks gebruikt en een die een sleutel voor de configuratie gebruikt.

Controleer de bereiken in een controlleractie met vastgelegde bereiken

Het volgende codefragment toont het gebruik van het kenmerk [RequiredScope] met vastgelegde bereiken.

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

Controleer de bereiken in een controlleractie met bereiken die zijn gedefinieerd in de configuratie

U kunt deze vereiste bereiken ook declareren in de configuratie en naar de configuratiesleutel verwijzen:

Als u bijvoorbeeld in appsettings.json de volgende configuratie hebt:

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

Verwijs er vervolgens naar in het kenmerk [RequiredScope]:

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

Bereiken voorwaardelijk verifiëren

Er zijn gevallen waarin u bereiken voorwaardelijk wilt controleren. U kunt dit doen met behulp van de VerifyUserHasAnyAcceptedScope-extensiemethode in de 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.
        // ...
    }
 // ...
}

De bereiken verifiëren op het niveau van de controller

U kunt de bereiken ook voor de hele controller verifiëren

Verifieer de bereiken in een controller met vastgelegde bereiken

Het volgende codefragment toont het gebruik van het kenmerk [RequiredScope] met vastgelegde bereiken op de controller. Als u de RequiredScopeAttribute wilt gebruiken, moet u het volgende doen:

• Gebruiken AddMicrosoftIdentityWebApi in Startup.cs, zoals te zien is in de codeconfiguratie
• of voeg anders het ScopeAuthorizationRequirement toe aan het autorisatiebeleid, zoals wordt uitgelegd in autorisatiebeleid.

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

Verifieer de bereiken in een controller met bereiken die zijn gedefinieerd in de configuratie

Net als bij een actie, kunt u deze vereiste bereiken ook declareren in de configuratie en naar de configuratiesleutel verwijzen:

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

De bereiken meer globaal verifiëren

Het definiëren van gedetailleerde bereiken voor uw web-API en het verifiëren van de bereiken in elke controlleractie is de aanbevolen aanpak. Het is echter ook mogelijk om de bereiken te verifiëren op het niveau van de toepassing of een controller. Zie autorisatie op basis van claims in de ASP.NET Core-documentatie voor meer informatie.

Wat wordt geverifieerd?

Het kenmerk [RequiredScope] en de methode VerifyUserHasAnyAcceptedScope. Dit werkt ongeveer als de volgende stappen:

• Verifiëren of er een claim met de naam http://schemas.microsoft.com/identity/claims/scope of scp is.
• Verifiëren of de claim een waarde heeft die het bereik bevat dat door de API wordt verwacht.

ASP.NET Klassiek

In een ASP.NET-toepassing kunt u bereiken op de volgende manier valideren:

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

Hieronder ziet u een vereenvoudigde versie van 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"
        });
    }
}

Raadpleeg ScopesRequiredHttpContextExtensions.cs voor een volledige versie van ValidateScopes ASP.NET Core

App-rollen verifiëren in API's die worden aangeroepen door daemon-apps

Als uw web-API wordt aangeroepen door een daemon-app, moet die app een toepassingsmachtiging voor uw web-API vereisen. Zoals wordt weergegeven in Toepassingsmachtigingen (app-rollen) beschikbaar maken worden dergelijke machtigingen beschikbaar gemaakt door uw API. Een voorbeeld is de app-rol access_as_application.

U moet nu uw API laten verifiëren of het token dat het ontvangt de roles-claim bevat en dat deze claim de verwachte waarde heeft. De verificatiecode is vergelijkbaar met de code die gedelegeerde machtigingen verifieert, behalve dat uw controlleractie op rollen in plaats van op bereiken test:

ASP.NET Core

Het volgende codefragment laat zien hoe u de toepassingsrol controleert;

using Microsoft.Identity.Web

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

In plaats daarvan kunt u de [Authorize(Roles = "access_as_application")] kenmerken op de controller of een actie (of een scheermespagina) gebruiken.

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

Autorisatie op basis van rollen in ASP.NET Core bevat verschillende benaderingen voor het implementeren van autorisatie op basis van rollen. Ontwikkelaars kunnen er een kiezen die bij hun respectieve scenario's past.

Zie de stapsgewijze zelfstudie voor web-apps over autorisatie op rollen en groepen voor praktische voorbeelden.

ASP.NET Klassiek

In een ASP.NET-toepassing kunt u app-rollen op de volgende manier valideren:

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

Een vereenvoudigde versie van ValidateAppRole is:

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

Raadpleeg RolesRequiredHttpContextExtensions.cs code voor een volledige versie van ValidateAppRole ASP.NET Core.

App-rollen verifiëren in API's die namens gebruikers worden aangeroepen

Gebruikers kunnen ook rollenclaims gebruiken in gebruikerstoewijzingspatronen, zoals wordt weergegeven in App-rollen toevoegen in uw toepassing en deze ontvangen in het token. Als de rollen aan beide kunnen worden toegewezen, kunnen door het controleren van rollen apps zich aanmelden als gebruikers en gebruikers zich aanmelden als apps. We raden u aan verschillende rollen voor gebruikers en apps te declareren om deze verwarring te voorkomen.

Als u app-rollen hebt gedefinieerd met gebruiker/groep, kunnen rollenclaims ook worden geverifieerd in de API, samen met bereiken. De verificatielogica van de app-rollen in dit scenario blijft hetzelfde als wanneer de API wordt aangeroepen door de daemon-apps, omdat er geen differentiatie is in de rolclaim voor gebruiker/groep en toepassing.

Tokens voor alleen apps accepteren als de web-API alleen door daemon-apps moet worden aangeroepen

Als u wilt dat alleen daemon-apps uw web-API aanroepen, voegt u als u de app-rol valideert de voorwaarde toe dat het token een token is dat alleen voor apps is.

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

Als u de omgekeerde voorwaarde inschakelt, kunnen alleen apps die een gebruiker aanmelden uw API aanroepen.

Autorisatie op basis van toegangsbeheerlijsten (ACL) gebruiken

U kunt uw web-API ook beveiligen met een autorisatiepatroon op basis van toegangsbeheerlijsten (ACL) om tokens zonder de roles-claim te beheren.

Als u Microsoft.Identity.Web gebruikmaakt van ASP.NET Core, moet u declareren dat u ACL-autorisatie gebruikt. Anders genereert Microsoft Identity Web een uitzondering wanneer de opgegeven claims geen rollen of bereiken bevatten:

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

Om deze uitzondering te voorkomen, stelt u de AllowWebApiToBeAuthorizedByACL configuratie-eigenschap true in op appsettings.json of programmatisch.

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

Als u dit instelt AllowWebApiToBeAuthorizedByACL true, is dit uw verantwoordelijkheid om het ACL-mechanisme te garanderen.

Volgende stappen

• Meer informatie door een ASP.NET Core-web-app te bouwen waarmee gebruikers worden aangemeld in de volgende reeks meerdelige zelfstudies

• Voorbeelden van web-API's van Microsoft Identity Platform verkennen