Autorização baseada em função no ASP.NET Core

Quando a identidade de um usuário é criada após a autenticação, o usuário pode pertencer a uma ou mais funções, refletindo várias autorizações que o usuário tem para acessar dados e executar operações. Por exemplo, Tracy pode pertencer às funções "Administrador" e "Usuário" com acesso a páginas da Web administrativas no aplicativo, enquanto Scott pode pertencer apenas à função "Usuário" e não ter acesso a dados administrativos ou operações. A forma como essas funções são criadas e gerenciadas depende do repositório de backup do processo de autorização. As funções são expostas ao desenvolvedor por meio de ClaimsPrincipal.IsInRole. AddRoles deve ser chamado para adicionar serviços de função ao configurar o sistema de identidade do aplicativo.

Embora as funções sejam declarações, nem todas as declarações são funções. Dependendo do emissor de identidade, uma função pode ser uma coleção de usuários que podem aplicar declarações para membros do grupo, bem como uma declaração real sobre uma identidade. No entanto, as declarações devem ser informações sobre um usuário individual. Usar funções para adicionar declarações a um usuário pode confundir o limite entre o usuário e suas declarações individuais. Essa confusão é a razão pela qual os modelos de SPA (aplicativo de página única) não são projetados em torno de funções. Além disso, para as organizações que migram de um sistema herdado local, a proliferação de funções ao longo dos anos pode significar que uma declaração de função pode ser muito grande para ser contida em um token utilizável por um SPA. Para proteger SPAs, consulte Use Identity para proteger um backend de API Web para SPAs.

Este artigo usa exemplos Razor de componente e se concentra em Blazor cenários de autorização. Para obter diretrizes adicionais Blazor , consulte a seção Recursos adicionais . Para obter diretrizes sobre Razor Pages e MVC, consulte os seguintes recursos:

• autorização baseada em Role em ASP.NET Core Razor Pages
• Autorização baseada em funções no ASP.NET Core MVC

Aplicativo de exemplo

O exemplo Blazor Web App deste artigo é o aplicativo de exemplo BlazorWebAppAuthorization (repositório GitHub dotnet/AspNetCore.Docs.Samples) (como baixar). O aplicativo de exemplo usa contas semeadas com funções pré-configuradas para demonstrar a maioria dos exemplos neste artigo. Para obter mais informações, consulte o arquivo README do exemplo (README.md).

Adicionar serviços de função ao Identity

builder.Services.AddDefaultIdentity<IdentityUser>( ... )
    .AddRoles<IdentityRole>()
    ...

builder.Services.AddIdentityCore<IdentityUser>()
    .AddRoles<IdentityRole>()
    ...

services.AddDefaultIdentity<IdentityUser>()
    .AddRoles<IdentityRole>()
    ...

services.AddIdentityCore<IdentityUser>()
    .AddRoles<IdentityRole>()
    ...

app.UseAuthentication(); // Only present if not called internally
app.UseAuthorization();

app.UseAuthentication(); // Only present if not called internally
app.UseAuthorization();

app.UseAuthentication(); // Only present if not called internally
app.UseAuthorization();

builder.Services.AddAuthorizationCore();

Verificações de autorização baseadas em função

Verificações de autorização baseadas em função:

• São declarativas e especificam funções das quais o usuário atual deve ser membro para acessar o recurso solicitado.
• São aplicados a Razor componentes (exemplos neste artigo), Razor páginas ou controladores MVC ou ações dentro de um controlador.

O AuthorizeView componente (AuthorizeView componente na documentação Blazor) dá suporte à autorização baseada em funções. Esta seção aborda conceitos básicos. Para obter cobertura completa, consulte ASP.NET Core Blazor autenticação e autorização.

Para autorização de conteúdo baseada em função em Razor componentes, use AuthorizeView.Roles parâmetro.

No exemplo a seguir:

• O usuário deve ter uma declaração de função para que as funções ou Admin as SuperUser funções vejam o conteúdo do primeiro AuthorizeView componente.
• Para exigir as declarações de função de ambos Admin e SuperUser, o segundo exemplo aninha componentes AuthorizeView.

Pages/RoleChecksWithAuthorizeView.razor:

@page "/role-checks-with-authorizeview"

<h3>Role Checks with AuthorizeView</h3>

<AuthorizeView Roles="Admin, SuperUser">
    <p>User: @context.User.Identity?.Name</p>
    <p>You have an 'Admin' or 'SuperUser' role claim.</p>
</AuthorizeView>

<AuthorizeView Roles="Admin">
    <p>User: @context.User.Identity?.Name</p>
    <p>You have the 'Admin' role claim.</p>
    <AuthorizeView Roles="SuperUser" Context="innerContext">
        <p>User: @innerContext.User.Identity?.Name</p>
        <p>You have both 'Admin' and 'SuperUser' role claims.</p>
    </AuthorizeView>
</AuthorizeView>

O código anterior estabelece um Context para o componente interno AuthorizeView para evitar uma colisão de contexto AuthenticationState. O contexto AuthenticationState é acessado no AuthorizeView externo utilizando a abordagem padrão para acesso ao contexto (@context.User). O contexto é acessado no AuthorizeView internos com o contexto nomeado innerContext (@innerContext.User).

O [Authorize] atributo dá suporte à autorização baseada em função para componentes inteiros Razor . Use o parâmetro AuthorizeAttribute.Roles. O código a seguir limita o acesso de componentes aos usuários que são membros da Admin função.

Pages/RequireAdminRoleWithAuthorizeAttribute.razor:

@page "/require-admin-role-with-authorize-attribute"
@using Microsoft.AspNetCore.Authorization
@attribute [Authorize(Roles = "Admin")]

<h1>Require 'Admin' role with [Authorize] attribute</h1>

<p>You can only see this if you're in the 'Admin' role.</p>

Várias funções podem ser especificadas como uma lista separada por vírgulas. No exemplo a seguir, o acesso é limitado aos usuários que são membros da Admin função ou da SuperUser função.

Pages/RequireAdminOrSuperUserRoleWithAuthorizeAttribute.razor:

@page "/require-admin-or-superuser-role-with-authorize-attribute"
@using Microsoft.AspNetCore.Authorization
@attribute [Authorize(Roles = "Admin, SuperUser")]

<h1>Require 'Admin' or 'SuperUser' role with [Authorize] attribute</h1>

<p>
    You can only see this if you're in the 'Admin' role or the 'SuperUser' role.
</p>

Quando vários atributos são aplicados, o usuário deve ser membro de todas as funções especificadas. O exemplo aAdmin seguir requer ambos osSuperUser papéis.

Pages/RequireAdminAndSuperUserRolesWithAuthorizeAttributes.razor:

@page "/require-admin-and-superuser-roles-with-authorize-attributes"
@using Microsoft.AspNetCore.Authorization
@attribute [Authorize(Roles = "Admin")]
@attribute [Authorize(Roles = "SuperUser")]

<h1>Require 'Admin' and 'SuperUser' roles with [Authorize] attributes</h1>

<p>
    You can only see this if you're in both the 'Admin' role 
    and the 'SuperUser' role.
</p>

A correspondência de função normalmente diferencia maiúsculas de minúsculas porque os nomes de função são armazenados e comparados usando comparações de cadeia de caracteres .NET. Por exemplo, Admin (maiúscula A) não é tratada como o mesmo papel que admin (minúscula a). Para obter mais informações, consulte a autorização baseada em Claim no ASP.NET Core.

Verificações de autorização baseadas em política

Os requisitos de função podem ser expressos usando a sintaxe da política, em que o aplicativo registra uma política na inicialização como parte da configuração do serviço de autorização.

No exemplo a seguir:

• A RequireAdminRole política especifica que os usuários devem estar na Admin função.
• A RequireSuperUserRole política especifica que os usuários devem estar na SuperUser função.

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("RequireAdminRole",
         policy => policy.RequireRole("Admin"))
    .AddPolicy("RequireSuperUserRole",
         policy => policy.RequireRole("SuperUser"));

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("RequireAdminRole",
        policy => policy.RequireRole("Admin"));
    options.AddPolicy("RequireSuperUserRole",
        policy => policy.RequireRole("SuperUser"));
});

services.AddAuthorization(options =>
{
    options.AddPolicy("RequireAdminRole",
        policy => policy.RequireRole("Admin"));
    options.AddPolicy("RequireSuperUserRole",
        policy => policy.RequireRole("SuperUser"));
});

Para autorização baseada em política com um componente AuthorizeView, use o parâmetro AuthorizeView.Policy com um único nome de política.

Pages/PassRequireAdminRolePolicy.razor:

@page "/pass-requireadminrole-policy-with-authorizeview"

<h1>Pass 'RequireAdminRole' policy with AuthorizeView</h1>

<AuthorizeView Policy="RequireAdminRole">
    <p>You satisfy the 'RequireAdminRole' policy.</p>
</AuthorizeView>

Caso o usuário precise cumprir uma das várias políticas, crie uma política que confirme que o usuário atende a outras políticas.

Para lidar com o caso em que o usuário deve satisfazer várias políticas simultaneamente, siga uma das seguintes abordagens:

• Crie uma política para AuthorizeView que confirme que o usuário atende a várias outras políticas.

• Aninhar as políticas em vários AuthorizeView componentes.

  Pages/PassRequireAdminRoleAndRequireSuperUserRolePoliciesWithAuthorizeViews.razor:

  @page "/pass-requireadminrole-and-requiresuperuserrole-policies-with-authorizeviews"
  
  <h1>
      Pass 'RequireAdminRole' and 'RequireSuperUserRole' policies with AuthorizeViews
  </h1>
  
  <AuthorizeView Policy="RequireAdminRole">
      <AuthorizeView Policy="RequireSuperUserRole" Context="innerContext">
          <p>
              You satisfy the 'RequireAdminRole' and 
              'RequireSuperUserRole' policies.
          </p>
      </AuthorizeView>
  </AuthorizeView>
  

Se ambos Roles e Policy estiverem definidos, a autorização será bem-sucedida somente quando ambas as condições forem atendidas. Ou seja, o usuário deve pertencer a pelo menos uma das funções especificadas e atender aos requisitos definidos pela política.

Se Roles e Policy não forem especificados, o AuthorizeView usará a política padrão:

• Usuários autenticados (conectados) estão autorizados.
• Usuários não autenticados (não conectados) não estão autorizados.

Ao contrário da correspondência de funções, que normalmente diferencia maiúsculas de minúsculas, a pesquisa de nome de política no ASP.NET Core normalmente não diferencia maiúsculas de minúsculas, portanto, RequireAdminRole e requireadminrole se referem à mesma política.

As políticas são aplicadas a um componente inteiro Razor usando a Policy propriedade no [Authorize] atributo.

Pages/PassRequireAdminRolePolicyWithAuthorizeAttribute.razor:

@page "/pass-requireadminrole-policy-with-authorize-attribute"
@using Microsoft.AspNetCore.Authorization
@attribute [Authorize(Policy = "RequireAdminRole")]

<h1>Pass RequireAdminRole policy with [Authorize] attribute</h1>

<p>You can only see this if the 'RequireAdminRole' policy is satisfied.</p>

Para especificar várias funções permitidas em um requisito, especifique as funções como parâmetros para o RequireRole método. No exemplo a seguir, os usuários são autorizados se pertencerem aos papéis AdminouSuperUser.

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("ElevatedRights", policy =>
        policy.RequireRole("Admin", "SuperUser"));

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("ElevatedRights", policy =>
        policy.RequireRole("Admin", "SuperUser"));
});

services.AddAuthorization(options =>
{
    options.AddPolicy("ElevatedRights", policy =>
        policy.RequireRole("Admin", "SuperUser"));
});

Se você quiser que a política exija todas as funções anteriores, encadeia as funções ao construtor de políticas ou especifique-as ao construtor de políticas individualmente em uma instrução lambda.

Encadeado ao construtor de políticas:

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("ElevatedRights", policy => 
        policy
            .RequireRole("Admin")
            .RequireRole("SuperUser"));

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("ElevatedRights",
        policy =>
        {
            policy.RequireRole("Admin");
            policy.RequireRole("SuperUser");
        });

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("ElevatedRights", policy => 
        policy
            .RequireRole("Admin")
            .RequireRole("SuperUser"));
});

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("ElevatedRights",
        policy =>
        {
            policy.RequireRole("Admin");
            policy.RequireRole("SuperUser");
        });
});

services.AddAuthorization(options =>
{
    options.AddPolicy("ElevatedRights", policy => 
        policy
            .RequireRole("Admin")
            .RequireRole("SuperUser"));
});

services.AddAuthorization(options =>
{
    options.AddPolicy("ElevatedRights",
        policy =>
        {
            policy.RequireRole("Admin");
            policy.RequireRole("SuperUser");
        });
});

Grupos de segurança do Windows Authentication como funções de aplicativo

O User.Identity é normalmente um WindowsIdentity ao usar a Autenticação do Windows, e você pode recuperar as reivindicações de grupo SID ou verificar se um usuário pertence a uma função com o seguinte código, onde o espaço reservado {DOMAIN} é o domínio e o {SID GROUP NAME} é o nome do grupo SID.

if (User.Identity is WindowsIdentity windowsIdentity)
{
    var groups = windowsIdentity.Groups;

    // If needed, obtain a list of the SID groups
    var securityGroups = 
        groups.Select(g => g.Translate(typeof(NTAccount)).ToString()).ToList();

    // If needed, obtain the user's Windows identity name
    var windowsIdentityName = windowsIdentity.Name;

    // Check if the user is in a specific SID group
    if (User.IsInRole(@"{DOMAIN}\{SID GROUP NAME}"))
    {
        // User is in the specified group
    }
    else
    {
        // User isn't in the specified group
    }
}
else
{
    // The user isn't authenticated with Windows Authentication
}

Recursos adicionais

• ASP.NET Core Blazor autenticação e autorização
• ASP.NET Core Blazor WebAssembly com grupos e papéis do Microsoft Entra ID
• Autorização baseada em funções nas Páginas do ASP.NET Core
• Autorização baseada em função no ASP.NET Core MVC
• Estender ou adicionar declarações personalizadas, incluindo declarações de função, usando IClaimsTransformation