Autenticação e autorização em APIs mínimas

Observação

Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 9 deste artigo.

Advertência

Esta versão do ASP.NET Core não é mais suportada. Para obter mais informações, consulte a Política de suporte do .NET e .NET Core. Para a versão atual, consulte a versão .NET 9 deste artigo.

Importante

Estas informações referem-se a um produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não oferece garantias, expressas ou implícitas, em relação às informações fornecidas aqui.

Para a versão atual, consulte a versão .NET 9 deste artigo.

As APIs mínimas suportam todas as opções de autenticação e autorização disponíveis no ASP.NET Core e fornecem algumas funcionalidades adicionais para melhorar a experiência de trabalho com autenticação.

Conceitos-chave em autenticação e autorização

A autenticação é o processo de determinar a identidade de um usuário. Autorização é o processo de determinar se um usuário tem acesso a um recurso. Ambos os cenários de autenticação e autorização compartilham semânticas de implementação semelhantes no ASP.NET Core. A autenticação é tratada pelo serviço de autenticação, IAuthenticationService, que é utilizado pelo middleware de autenticação. A autorização é gerida pelo serviço de autorização, IAuthorizationService, utilizado pelo middleware de autorização.

O serviço de autenticação usa manipuladores de autenticação registrados para concluir ações relacionadas à autenticação. Por exemplo, uma ação relacionada à autenticação é autenticar um utilizador ou terminar sessão de um utilizador. Esquemas de autenticação são nomes usados para identificar exclusivamente um manipulador de autenticação e suas opções de configuração. Os manipuladores de autenticação são responsáveis por implementar as estratégias de autenticação e gerar as declarações de um usuário dada uma estratégia de autenticação específica, como OAuth ou OIDC. As opções de configuração também são exclusivas para a estratégia e fornecem ao manipulador uma configuração que afeta o comportamento de autenticação, como URIs de redirecionamento.

Há duas estratégias para determinar o acesso do usuário aos recursos na camada de autorização:

• As estratégias baseadas em função determinam o acesso de um usuário com base na função que lhe é atribuída, como Administrator ou User. Para obter mais informações sobre autorização baseada em função, consulte documentação de autorização baseada em função.
• As estratégias baseadas em declarações determinam o acesso de um utilizador com base nas declarações emitidas por uma autoridade central. Para obter mais informações sobre autorização baseada em declaração, consulte documentação de autorização baseada em declaração.

No ASP.NET Core, ambas as estratégias são capturadas em um requisito de autorização. O serviço de autorização aproveita os manipuladores de autorização para determinar se um determinado usuário atende ou não aos requisitos de autorização aplicados a um recurso.

Habilitando a autenticação em aplicativos mínimos

Para habilitar a autenticação, ligue para AddAuthentication para registrar os serviços de autenticação necessários no provedor de serviços do aplicativo.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Normalmente, uma estratégia de autenticação específica é usada. No exemplo a seguir, o aplicativo é configurado com suporte para autenticação baseada em portador JWT. Este exemplo usa as APIs disponíveis no pacote Microsoft.AspNetCore.Authentication.JwtBearer NuGet.

var builder = WebApplication.CreateBuilder(args);
// Requires Microsoft.AspNetCore.Authentication.JwtBearer
builder.Services.AddAuthentication().AddJwtBearer();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Por padrão, o WebApplication registra automaticamente os middlewares de autenticação e autorização se determinados serviços de autenticação e autorização estiverem habilitados. No exemplo a seguir, não é necessário invocar UseAuthentication ou UseAuthorization para registrar os middlewares porque WebApplication faz isso automaticamente depois de AddAuthentication ou AddAuthorization serem chamados.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Em alguns casos, nomeadamente ao controlar a ordem do middleware, é necessário registar explicitamente a autenticação e a autorização. No exemplo a seguir, o middleware de autenticação é executado após o middleware CORS tenha sido executado. Para obter mais informações sobre middlewares e esse comportamento automático, consulte Middleware em aplicativos de API mínima.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCors();
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/", () => "Hello World!");
app.Run();

Configurando a estratégia de autenticação

As estratégias de autenticação normalmente suportam uma variedade de configurações que são carregadas por meio de opções. Aplicações mínimas suportam opções de carregamento a partir da configuração para as seguintes estratégias de autenticação:

• baseado em portador de JWT
• baseada em conexão OpenID

A estrutura ASP.NET Core espera encontrar essas opções na seção Authentication:Schemes:{SchemeName} da configuração . Na amostra a seguir, dois esquemas diferentes, Bearer e LocalAuthIssuer, são definidos com suas respetivas opções. A opção Authentication:DefaultScheme pode ser usada para configurar a estratégia de autenticação padrão usada.

{
  "Authentication": {
    "DefaultScheme":  "LocalAuthIssuer",
    "Schemes": {
      "Bearer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "dotnet-user-jwts"
      },
      "LocalAuthIssuer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "local-auth"
      }
    }
  }
}

No Program.cs, duas estratégias de autenticação baseadas no portador do JWT são registradas, com:

• Nome do esquema "Bearer".
• Nome do esquema "LocalAuthIssuer".

"Bearer" é o esquema padrão típico em aplicações com suporte a JWT-bearer, mas o esquema padrão pode ser substituído ao definir a propriedade DefaultScheme conforme demonstrado no exemplo anterior.

O nome do esquema é usado para identificar exclusivamente uma estratégia de autenticação e é usado como a chave de pesquisa ao resolver opções de autenticação da configuração, conforme mostrado no exemplo a seguir:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication()
  .AddJwtBearer()
  .AddJwtBearer("LocalAuthIssuer");
  
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Configurando políticas de autorização em aplicativos mínimos

A autenticação é usada para identificar e validar a identidade dos usuários em relação a uma API. A autorização é utilizada para validar e verificar o acesso a recursos numa API e é facilitada pelo IAuthorizationService registado pelo método de extensão AddAuthorization. No cenário a seguir, um recurso de /hello é adicionado que requer que um usuário apresente uma declaração de função admin com uma declaração de escopo greetings_api.

A configuração de requisitos de autorização em um recurso é um processo de duas etapas que exige:

1. Configurando os requisitos de autorização em uma política globalmente.
2. Aplicação de políticas individuais aos recursos.

No código a seguir, AddAuthorizationBuilder é invocado, o que:

• Adiciona serviços relacionados à autorização ao contêiner DI.
• Retorna um AuthorizationBuilder que pode ser usado para registrar diretamente as políticas de autorização.

O código cria uma nova política de autorização, chamada admin_greetings, que encapsula dois requisitos de autorização:

• Um requisito baseado em função via RequireRole para usuários com uma função admin.
• Um requisito baseado em declaração via RequireClaim que o usuário deve fornecer uma declaração de escopo greetings_api.

A política de admin_greetings é fornecida como uma política necessária para o ponto de extremidade /hello.

using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorizationBuilder()
  .AddPolicy("admin_greetings", policy =>
        policy
            .RequireRole("admin")
            .RequireClaim("scope", "greetings_api"));

var app = builder.Build();

app.MapGet("/hello", () => "Hello world!")
  .RequireAuthorization("admin_greetings");

app.Run();

Use o dotnet user-jwts para testes de desenvolvimento

Ao longo deste artigo, uma aplicação configurada com autenticação baseada em portador JWT é usada. A autenticação baseada no portador JWT requer que os clientes apresentem um token no cabeçalho da solicitação para validar sua identidade e declarações. Normalmente, esses tokens são emitidos por uma autoridade central, como um servidor de identidade.

Ao desenvolver na máquina local, a ferramenta dotnet user-jwts pode ser usada para criar tokens de portador.

dotnet user-jwts create

Observação

Quando invocada em um projeto, a ferramenta adiciona automaticamente as opções de autenticação correspondentes ao token gerado ao appsettings.json.

Os tokens podem ser configurados com uma variedade de personalizações. Por exemplo, para criar um token para a função admin e o escopo greetings_api, conforme esperado pela política de autorização no código anterior:

dotnet user-jwts create --scope "greetings_api" --role "admin"

O token gerado pode então ser enviado como parte do cabeçalho na ferramenta de teste de escolha. Por exemplo, com curl:

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/hello

Para obter mais informações sobre a ferramenta dotnet user-jwts, leia a documentação completa.