Partilhar via

Tutorial: Criar e proteger uma API Web ASP.NET Core com a plataforma de identidade da Microsoft

  • Artigo

Aplica-se a: círculo verde com um símbolo de marca de verificação branco. Os locatários do Workforce círculo verde com um símbolo de marca de verificação branco. Inquilinos externos (saber mais)

Esta série de tutoriais demonstra como proteger uma API Web ASP.NET Core com a plataforma de identidade da Microsoft para limitar seu acesso apenas a usuários autorizados e aplicativos cliente. A API da Web que você cria usa permissões delegadas (escopos) e permissões de aplicativo (funções de aplicativo).

Neste tutorial, você:

  • Crie uma API Web ASP.NET Core
  • Configurar a API web para usar os detalhes de registo da aplicação Microsoft Entra
  • Proteja seus pontos de extremidade da API da Web
  • Execute a API da Web para garantir que ela esteja ouvindo solicitações HTTP

Pré-requisitos

Criar um novo projeto de API Web ASP.NET Core

Para criar um projeto mínimo de API Web ASP.NET Core, siga estas etapas:

  1. Abra seu terminal no Visual Studio Code ou em qualquer outro editor de código e navegue até o diretório onde você deseja criar seu projeto.

  2. Execute os seguintes comandos na CLI do .NET ou em qualquer outra ferramenta de linha de comando.

    dotnet new webapi -n MyProtectedApi
cd MyProtectedApi

  3. Selecione Sim quando uma caixa de diálogo perguntar se você deseja confiar nos autores.

  4. Selecione Sim Quando uma caixa de diálogo perguntar se você deseja adicionar os ativos necessários ao projeto.

Instalar pacotes necessários

Para proteger uma API Web ASP.NET Core, você precisa do pacote Microsoft.Identity.Web - um conjunto de bibliotecas ASP.NET Core que simplificam a adição de suporte de autenticação e autorização a aplicativos Web e APIs Web que se integram à plataforma de identidade da Microsoft.

Para instalar o pacote, use:

dotnet add package Microsoft.Identity.Web

Configurar detalhes de registro do aplicativo

Abra o arquivo appsettings.json na pasta do aplicativo e adicione os detalhes de registro do aplicativo que você gravou depois de registrar a API da Web.

{
    "AzureAd": {
        "Instance": "Enter_the_Authority_URL_Here",
        "TenantId": "Enter_the_Tenant_Id_Here",
        "ClientId": "Enter_the_Application_Id_Here",
    },
    "Logging": {...},
  "AllowedHosts": "*"
}

Substitua os seguintes espaços reservados, conforme mostrado:

  • Substitua Enter_the_Application_Id_Here pelo ID do aplicativo (cliente).
  • Substitua Enter_the_Tenant_Id_Here pelo ID do diretório (tenant).
  • Substitua Enter_the_Authority_URL_Here pelo URL da Authority, conforme explicado na próxima seção.

URL de autoridade para seu aplicativo

A URL de autoridade especifica o diretório do qual a Biblioteca de Autenticação da Microsoft (MSAL) pode solicitar tokens. Ele é construído de forma diferente tanto na força de trabalho quanto nos locatários externos, como mostrado:

//Instance for workforce tenant
Instance: "https://login.microsoftonline.com/"

Usar domínio de URL personalizado (opcional)

Domínios de URL personalizados não são suportados em locatários da força de trabalho.

Adicionar função e escopo do aplicativo

Todas as APIs devem publicar um mínimo de um escopo, também chamado de permissão delegada, para que os aplicativos cliente obtenham um token de acesso para um usuário com êxito. As APIs também devem publicar pelo menos uma função de aplicativo, também chamadas de permissões de aplicativo, para que as aplicações cliente possam obter um token de acesso por si mesmas, ou seja, quando um utilizador não está a iniciar sessão.

Especificamos essas permissões no arquivo appsettings.json. Neste tutorial, você registra permissões delegadas e de aplicativo com os escopos "Forecast.Read". Isso significa que apenas usuários ou aplicativos cliente que chamam a API com um token de acesso contendo o escopo "Forecast.Read" são autorizados a acessar o ponto de extremidade protegido.

{
  "AzureAd": {
    "Instance": "Enter_the_Authority_URL_Here",
    "TenantId": "Enter_the_Tenant_Id_Here",
    "ClientId": "Enter_the_Application_Id_Here",
    "Scopes": {
      "Read": "Forecast.Read",
    },
    "AppPermissions": {
      "Read": ["Forecast.Read"],
    }
  },
  "Logging": {...},
  "AllowedHosts": "*"
}

Implementar autenticação e autorização na API

Para configurar a autenticação e autorização, abra o arquivo program.cs e substitua seu conteúdo os seguintes trechos de código:

Adicionar um esquema de autenticação

Nesta API, usamos o esquema JSON Web Token (JWT) Bearer como o mecanismo de autenticação padrão. Use o método AddAuthentication para registrar o esquema de portador JWT.

// Import the required packages

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Configure authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(options =>
    {
        builder.Configuration.Bind("AzureAd", options);
        options.TokenValidationParameters.NameClaimType = "name";
    }, options => { builder.Configuration.Bind("AzureAd", options); });

Configurar autorização

A autorização determina o que um usuário autenticado tem permissão para fazer. Definimos uma política chamada AuthZPolicy que exige que o cliente que chama a API tenha a função Forecast.Read para aplicativos cliente ou o escopo Forecast.Read para um usuário conectado.

builder.Services.AddAuthorization(config =>
{
config.AddPolicy("AuthZPolicy", policy =>
    policy.RequireRole("Forecast.Read"));
});

O método AddPolicy cria uma política nomeada (AuthZPolicy) que verifica a presença da função Forecast.Read nas declarações de token do usuário. Se o token não tiver a declaração roles, o acesso aos endpoints que exigem essa política será negado.

Criar o pipeline de solicitação HTTP

Neste tutorial, usamos uma API mínima sem controladores, pois o foco está mais na proteção da API. Configuramos o pipeline de middleware da API adicionando o seguinte:

  • de redirecionamento HTTPS: imponha uma comunicação segura redirecionando solicitações HTTP para HTTPS.
  • Middleware de autenticação: valida tokens de entrada antes de processar solicitações.
  • middleware de autorização: aplica políticas após a autenticação, garantindo que apenas clientes autorizados possam acessar pontos de extremidade protegidos.
var app = builder.Build();

// Configure the HTTP request pipeline

app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();

Definir o ponto final da previsão meteorológica

O ponto final /weatherforecast gera uma previsão aleatória de cinco dias, protegida por a política de autorização. RequireAuthorization("AuthZPolicy") garante que apenas clientes com a função Forecast.Read possam acessá-lo.

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast =  Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
    
        summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("weatherForecast")
.RequireAuthorization("AuthZPolicy"); // Protect this endpoint with the AuthZPolicy

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

O fluxo de autenticação e autorização na API Web de exemplo que criamos funciona da seguinte maneira:

  • O cliente envia uma solicitação GET para /weatherforecast com um JWT no cabeçalho Authorization.
  • UseAuthentication valida o token em relação ao Microsoft Entra ID
  • UseAuthorization verifica o papel de Forecast.Read nas declarações do token.
  • Se for bem-sucedido, o ponto de extremidade retorna a previsão; caso contrário, ele responde com 401 Unauthorized (inválido/sem token) ou 403 Forbidden (função ausente).

Executa a tua API

Execute sua API para garantir que ela esteja sendo executada sem erros usando o comando dotnet run. Se você pretende usar o protocolo HTTPS mesmo durante o teste, você precisa confiança . O certificado de desenvolvimento da NET.

  1. Inicie o aplicativo digitando o seguinte no terminal:

    dotnet run

  2. Uma saída semelhante à seguinte deve ser exibida no terminal. Isto confirma que a aplicação está a correr em http://localhost:{port} e à espera de solicitações.

    Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

A página da Web http://localhost:{host} exibe uma saída semelhante à imagem a seguir. Isso ocorre porque a API está sendo chamada sem autenticação. Para fazer uma chamada autorizada, consulte Próximas etapas para obter orientação sobre como acessar uma API da Web protegida.

Captura de tela que mostra o erro 401 quando a página da Web é iniciada.

Para obter um exemplo completo do código desta API, consulte o arquivo de exemplos .

Próximos passos

Parte 2: Testar sua API da Web ASP.NET Core protegida