Skyddat webb-API: Verifiera omfång och applikationsroller

I ASP.NET Core kan du använda Microsoft.Identity.Web för att verifiera omfång i varje kontrollantåtgärd. Du kan också verifiera dem på kontrollantnivå eller för hela programmet.

Verifiera omfattningarna för varje kontrolleråtgärd

Du kan kontrollera omfången i kontrollantåtgärden med hjälp av attributet [RequiredScope] . Det här attributet har flera åsidosättningar. En som tar de nödvändiga behörigheterna direkt och en som tar en nyckel till konfigurationen.

Verifiera omfången för en kontrollantåtgärd med hårdkodade värden

Följande kodfragment visar användningen av [RequiredScope] attributet med hårdkodade omfång.

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

Verifiera omfången för en kontrollantåtgärd med omfång som definierats i konfigurationen

Du kan också deklarera de här nödvändiga omfången i konfigurationen och referera till konfigurationsnyckeln:

Om du till exempel har följande konfiguration i appsettings.json :

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

Referera sedan till det i attributet [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.
        // ...
    }
 // ...
}

Verifiera omfång villkorligt

Det finns fall där du vill verifiera omfång villkorligt. Du kan göra detta med hjälp av VerifyUserHasAnyAcceptedScope tilläggsmetoden på 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.
        // ...
    }
 // ...
}

Kontrollera omfången på kontrollenhetsnivå

Du kan också verifiera omfången för hela kontrollern

Verifiera omfången på en kontroller med hårdkodade omfång

Följande kodfragment visar användningen av [RequiredScope]-attributet med hårdkodade scopes på kontrollern. Om du vill använda RequiredScopeAttribute måste du antingen:

• Använd AddMicrosoftIdentityWebApi i Startup.cs, som du ser i Kodkonfiguration
• eller på annat sätt lägg till ScopeAuthorizationRequirement i auktoriseringsprinciperna enligt beskrivningen i auktoriseringsprinciper.

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

Verifiera omfången på en kontrollant med omfång som definierats i konfigurationen

Precis som vid åtgärd kan du även deklarera de här nödvändiga omfången i konfigurationen och referera till konfigurationsnyckeln:

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

Verifiera omfången mer globalt

Att definiera detaljerade omfång för webb-API:et och verifiera omfången i varje kontrollantåtgärd är den rekommenderade metoden. Men det är också möjligt att verifiera behörighetsomfången på programnivå eller kontrollernivå. Mer information finns i anspråksbaserad auktorisering i ASP.NET Core-dokumentationen.

Vad är verifierat?

Attributet [RequiredScope] och VerifyUserHasAnyAcceptedScope metoden gör något som liknar följande steg:

• Kontrollera att det finns ett anspråk med namnet http://schemas.microsoft.com/identity/claims/scope eller scp.
• Kontrollera att anspråket har ett värde som innehåller det omfång som förväntas av API:et.

I ett ASP.NET program kan du verifiera omfång på följande sätt:

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

Nedan visas en förenklad version av 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"
        });
    }
}

En fullständig version av ValidateScopes för ASP.NET Core finns i ScopesRequiredHttpContextExtensions.cs

Följande kodfragment visar hur du verifierar programrollen.

using Microsoft.Identity.Web

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

I stället kan du använda attributen [Authorize(Roles = "access_as_application")] på kontrollern eller en action (eller en Razor-sida).

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

Rollbaserad auktorisering i ASP.NET Core innehåller flera metoder för att implementera rollbaserad auktorisering. Utvecklare kan välja en av dem som passar deras respektive scenarier.

Praktiska exempel finns i den inkrementella självstudiekursen om auktorisering av roller och grupper i webbappen.

I en ASP.NET-applikation kan du verifiera applikationsroller på följande sätt:

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

En förenklad version av ValidateAppRole är:

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

För en fullständig version av ValidateAppRole för ASP.NET Core, hänvisa till koden RolesRequiredHttpContextExtensions.cs.