API da Web protegida: configuração de código

A Microsoft recomenda que você use o pacote NuGet Microsoft.Identity.Web ao desenvolver uma API da Web com o ASP.NET Core.

Microsoft.Identity.Web fornece a cola entre ASP.NET Core, o middleware de autenticação e a Microsoft Authentication Library (MSAL) para .NET. Ele permite uma experiência de desenvolvedor mais clara e robusta e aproveita o poder da plataforma de identidade da Microsoft e do Azure AD B2C.

ASP.NET para .NET 6.0

Para criar um novo projeto de API da Web que usa Microsoft.Identity.Web, use um modelo de projeto na CLI do .NET 6.0 ou Visual Studio.

CLI do núcleo Dotnet

# Create new web API that uses Microsoft.Identity.Web
dotnet new webapi --auth SingleOrg

Visual Studio - Para criar um projeto de API da Web no Visual Studio, selecione > Web Principal.

Os modelos de projeto .NET CLI e Visual Studio criam um arquivo de Program.cs semelhante a esse trecho de código. Aviso Microsoft.Identity.Web usando diretiva e as linhas que contêm autenticação e autorização.

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

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

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

app.MapControllers();

app.Run();

A Microsoft recomenda que você use o pacote NuGet Microsoft.Identity.Web.OWIN ao desenvolver uma API da Web com ASP.NET.

Microsoft.Identity.Web.OWIN fornece a cola entre ASP.NET, o middleware de autenticação ASP.NET e a Biblioteca de Autenticação da Microsoft (MSAL) para .NET. Ele permite uma experiência de desenvolvedor mais clara e robusta e aproveita o poder da plataforma de identidade da Microsoft e do Azure AD B2C.

Ele usa o mesmo arquivo de configuração que ASP.NET Core (appsettings.json) e você precisa se certificar de que esse arquivo é copiado com a saída do seu projeto (cópia de propriedade sempre nas propriedades do arquivo no Visual Studio ou no .csproj)

Microsoft.Identity.Web.OWIN adiciona um método de extensão ao IAppBuilder chamado AddMicrosoftIdentityWebApi. Esse método toma como parâmetro uma instância da OwinTokenAcquirerFactory qual você recebe chamadas OwinTokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>() e que apresenta uma instância à qual você pode adicionar muitos serviços para chamar APIs downstream ou configurar o cache de IServiceCollection token.

Aqui está um código de exemplo para Startup.Auth.cs. O código completo está disponível em tests/DevApps/aspnet-mvc/OwinWebApp

using Microsoft.Owin.Security;
using Microsoft.Owin.Security.Cookies;
using Owin;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Client;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web.OWIN;
using System.Web.Services.Description;

namespace OwinWebApp
{
    public partial class Startup
    {
        public void ConfigureAuth(IAppBuilder app)
        {
            app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);
            app.UseCookieAuthentication(new CookieAuthenticationOptions());

            OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

            app.AddMicrosoftIdentityWebApp(factory);
            factory.Services
                .Configure<ConfidentialClientApplicationOptions>(options => { options.RedirectUri = "https://localhost:44386/"; })
                .AddMicrosoftGraph()
                .AddDownstreamApi("DownstreamAPI1", factory.Configuration.GetSection("DownstreamAPI"))
                .AddInMemoryTokenCaches();
            factory.Build();
        }
    }
}

--

Validação de token

No trecho anterior, o middleware JwtBearer, como o middleware OpenID Connect em aplicativos Web, valida o token com base no valor de TokenValidationParameters. O token é descriptografado conforme necessário, as declarações são extraídas e a assinatura é verificada. Em seguida, o middleware valida o token verificando estes dados:

• Público-alvo: o token é direcionado para a API da Web.
• Sub: Foi emitido para um aplicativo que tem permissão para chamar a API da Web.
• Emissor: foi emitido por um serviço de token de segurança confiável (STS).
• Prazo de validade: A sua vida útil está ao alcance.
• Assinatura: Não foi adulterado.

Também pode haver validações especiais. Por exemplo, é possível validar que as chaves de assinatura, quando incorporadas em um token, são confiáveis e que o token não está sendo reproduzido. Finalmente, alguns protocolos requerem validações específicas.

Validadores

As etapas de validação são capturadas em validadores, que são fornecidos pela biblioteca de código aberto Microsoft IdentityModel Extensions for .NET . Os validadores são definidos no arquivo de origem da biblioteca Microsoft.IdentityModel.Tokens/Validators.cs.

Esta tabela descreve os validadores:

Personalizando a validação de token

Os validadores estão associados às propriedades da classe TokenValidationParameters . As propriedades são inicializadas a partir da configuração ASP.NET e ASP.NET Core.

Na maioria dos casos, não é necessário alterar os parâmetros. Os aplicativos que não são locatários individuais são exceções. Estas aplicações Web aceitam utilizadores de qualquer organização ou de contas Microsoft pessoais. Neste caso, os emitentes devem ser validados. Microsoft.Identity.Web também cuida da validação do emissor.

No ASP.NET Core, se você quiser personalizar os parâmetros de validação de token, use o seguinte trecho em seu Startup.cs:

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddMicrosoftIdentityWebApi(Configuration);
services.Configure<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme, options =>
{
  options.TokenValidationParameters.ValidAudiences = new[] { /* list of valid audiences */};
});

Para ASP.NET MVC, o exemplo de código a seguir mostra como fazer a validação de token personalizado:

https://github.com/azure-samples/active-directory-dotnet-webapi-manual-jwt-validation

Validação de token no Azure Functions

Você também pode validar tokens de acesso de entrada no Azure Functions. Você pode encontrar exemplos dessa validação nos seguintes exemplos de código no GitHub:

• .NET: Azure-Samples/ms-identity-dotnet-webapi-azurefunctions
• Node.js: Azure-Samples/ms-identity-nodejs-webapi-azurefunctions
• Python: Azure-Samples/ms-identity-python-webapi-azurefunctions)

Próximos passos

Passe para o próximo artigo neste cenário, Verificar escopos e funções de aplicativo em seu código.