API da Web protegida: verifique escopos e funções do aplicativo

No ASP.NET Core, você pode usar Microsoft.Identity.Web para verificar escopos em cada ação do controlador. Você também pode verificá-los no nível do controlador ou para todo o aplicativo.

Verificar os escopos em cada ação do controlador

Você pode verificar os escopos na ação do controlador usando o [RequiredScope] atributo. Este atributo tem várias substituições. Um que usa os escopos necessários diretamente e outro que leva uma chave para a configuração.

Verificar os escopos em uma ação do controlador com escopos codificados

O trecho de código a seguir mostra o uso do atributo com escopos [RequiredScope] codificados.

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

Verificar os escopos em uma ação do controlador com escopos definidos na configuração

Você também pode declarar esses escopos necessários na configuração e fazer referência à chave de configuração:

Por exemplo, se, em appsettings.json você tiver a seguinte configuração:

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

Em seguida, faça referência a ele no [RequiredScope] atributo:

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

Verificar escopos condicionalmente

Há casos em que você deseja verificar os escopos condicionalmente. Você pode fazer isso usando o VerifyUserHasAnyAcceptedScope método de extensão no 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.
        // ...
    }
 // ...
}

Verificar os escopos no nível do controlador

Você também pode verificar os escopos para todo o controlador

Verificar os escopos em um controlador com escopos codificados

O trecho de código a seguir mostra o uso do atributo com escopos [RequiredScope] codificados no controlador. Para usar o RequiredScopeAttribute, você precisará:

• Uso AddMicrosoftIdentityWebApi em Startup.cs, como visto na configuração de código
• ou, de outra forma, adicione o às políticas de autorização, conforme explicado ScopeAuthorizationRequirement em Políticas de autorização.

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

Verificar os escopos em um controlador com escopos definidos na configuração

Como na ação, você também pode declarar esses escopos necessários na configuração e fazer referência à chave de configuração:

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

Verificar os escopos de forma mais global

Definir escopos granulares para sua API da Web e verificar os escopos em cada ação do controlador é a abordagem recomendada. No entanto, também é possível verificar os escopos no nível do aplicativo ou de um controlador. Para obter detalhes, consulte autorização baseada em declaração na documentação do ASP.NET Core.

O que é verificado?

O [RequiredScope] atributo e VerifyUserHasAnyAcceptedScope o método, faz algo como as seguintes etapas:

• Verifique se há uma declaração com o nome http://schemas.microsoft.com/identity/claims/scope ou scp.
• Verifique se a declaração tem um valor que contém o escopo esperado pela API.

Em um aplicativo ASP.NET, você pode validar escopos da seguinte maneira:

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

Abaixo está uma versão simplificada de 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"
        });
    }
}

Para obter uma versão completa do ValidateScopes para ASP.NET Core, consulte ScopesRequiredHttpContextExtensions.cs

O trecho de código a seguir mostra como verificar a função do aplicativo;

using Microsoft.Identity.Web

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

Em vez disso, você pode usar os [Authorize(Roles = "access_as_application")] atributos no controlador ou uma ação (ou uma página de barbear).

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

A autorização baseada em função no ASP.NET Core lista várias abordagens para implementar a autorização baseada em função. Os desenvolvedores podem escolher um entre eles que se adapte aos seus respetivos cenários.

Para obter exemplos de trabalho, consulte o tutorial incremental do aplicativo Web sobre autorização por funções e grupos.

Em um aplicativo ASP.NET, você pode validar funções de aplicativo da seguinte maneira:

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

Uma versão simplificada do ValidateAppRole é:

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

Para obter uma versão completa do ValidateAppRole para ASP.NET Core, consulte RolesRequiredHttpContextExtensions.cs código.