Guia de início rápido: Proteger uma API Web ASP.NET Core com a plataforma de identidade da Microsoft

Artigo
02/03/2024

Seja bem-vindo! Essa provavelmente não é a página que você esperava. Enquanto trabalhamos em uma correção, este link direcionará você para o artigo certo:

Início Rápido: chamar uma API Web do ASP.NET Core que esteja protegida pela plataforma de identidade da Microsoft

Pedimos desculpas pela inconveniência e agradecemos sua paciência enquanto trabalhamos para resolver isso.

O início rápido a seguir usa um exemplo de código da API Web ASP.NET Core para demonstrar como restringir o acesso de recursos a contas autorizadas. O exemplo dá suporte à autorização de contas Microsoft pessoais e contas em qualquer organização do Microsoft Entra.

Pré-requisitos

Conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Locatário do Microsoft Entra
Um requisito mínimo do SDK 6.0 do .NET
Visual Studio 2022 ou Visual Studio Code

Etapa 1: Registrar o aplicativo

Primeiro, registre a API Web no seu locatário do Microsoft Entra e adicione um escopo seguindo estas etapas:

Entre no Centro de administração do Microsoft Entra pelo menos como um Administrador de Aplicativo.
Navegue até Identidade>Aplicativos>Registros do aplicativo.
Selecione Novo registro.
Em Nome, insira um nome para o aplicativo. Por exemplo, insira AspNetCoreWebApi-Quickstart. Os usuários do aplicativo verão esse nome e poderão ser alterados posteriormente.
Selecione Registrar.
Em Gerenciar, selecione Expor uma API>Adicionar um escopo. Em URI da ID do Aplicativo, aceite o padrão selecionando Salvar e continuar e insira os seguintes detalhes:

Nome do escopo: access_as_user
Quem pode consentir? : Administradores e usuários
Nome de exibição de consentimento do administrador: Access AspNetCoreWebApi-Quickstart
Descrição do consentimento do administrador:Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
Nome de exibição do consentimento do usuário: Access AspNetCoreWebApi-Quickstart
Descrição do consentimento do usuário: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
Estado: Enabled

Selecione Adicionar escopo para concluir a adição do escopo.

Etapa 2: Baixar o projeto do ASP.NET Core

Baixe a solução do ASP.NET Core no GitHub.

Observação

O exemplo de código atualmente tem como destino o ASP.NET Core 3.1. O exemplo pode ser atualizado para usar o .NET Core 6.0 e é abordado nas seguintes etapas: Atualizar o código de exemplo para ASP.NET Core 6.0. Este início rápido será preterido em um futuro próximo e será atualizado para usar o .NET 6.0.

Etapa 3: Configurar o projeto do ASP.NET Core

Nesta etapa, o código de exemplo será configurado para trabalhar com o registro do aplicativo criado anteriormente.

Extraia o arquivo .zip para uma pasta local próxima à raiz do disco para evitar erros causados por limitações de comprimento de caminho no Windows. Por exemplo, extraia em C:\Azure-Samples.
Abra a solução na pasta webapi no editor de códigos.
Em appsettings.json, substitua os valores de ClientId e TenantId.
```
"ClientId": "Enter_the_Application_Id_here",
"TenantId": "Enter_the_Tenant_Info_Here"
```
- Enter_the_Application_Id_Here é a ID do aplicativo (cliente) que você registrou.
- Substitua Enter_the_Tenant_Info_Here por um dos seguintes:
  - Se o aplicativo dá suporte às Contas somente neste diretório organizacional, substitua esse valor pela ID de diretório (locatário) (um GUID) ou pelo nome do locatário (por exemplo, contoso.onmicrosoft.com). A ID de diretório (locatário) pode ser encontrada na página Visão geral do aplicativo.
  - Se o aplicativo der suporte a Contas em qualquer diretório organizacional, substitua esse valor por organizations.
  - Se o aplicativo der suporte a Todos os usuários de contas Microsoft, defina esse valor como common.

Para este guia de início rápido, não altere nenhum outro valor no arquivo appsettings.json.

Etapa 4: atualizar o código de exemplo para ASP.NET Core 6.0

Para atualizar o exemplo de código para ASP.NET Core 6.0, siga estas etapas:

Abra webapi.csproj
Remova a seguinte linha:

<TargetFramework>netcoreapp3.1</TargetFramework>

Adicione a seguinte linha em seu lugar:

<TargetFramework>netcoreapp6.0</TargetFramework>

Esta etapa garantirá que o exemplo esteja voltado para a estrutura do .NET Core 6.0.

Etapa 5: executar o exemplo

Abra um terminal e altere o diretório para a pasta do projeto.
```
cd webapi
```
Execute o seguinte comando para criar a solução:

dotnet run

Se o build tiver sido bem-sucedido, a seguinte saída será exibida:

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

Como o exemplo funciona

Classe de inicialização

O middleware Microsoft.AspNetCore.Authentication usa a classe Startup que é executada quando o processo de hospedagem é iniciado. No método ConfigureServices, o método de extensão AddMicrosoftIdentityWebApi fornecido pelo Microsoft.Identity.Web é chamado.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

O método AddAuthentication() configura o serviço para adicionar a autenticação baseada em JwtBearer.

A linha que contém .AddMicrosoftIdentityWebApi adiciona a autorização da plataforma de identidade da Microsoft à API Web. Em seguida, ela é configurada para validar os tokens de acesso emitidos pela plataforma de identidade da Microsoft com base nas informações na seção AzureAD do arquivo de configuração appsettings.json:

chave appsettings.json	Descrição
`ClientId`	ID do aplicativo (cliente) referente ao aplicativo registrado.
`Instance`	Ponto de extremidade do STS (serviço de token de segurança) para o usuário se autenticar. Esse valor geralmente é `https://login.microsoftonline.com/`, indicando a nuvem pública do Azure.
`TenantId`	Nome do seu locatário ou sua ID de locatário (um GUID) ou `common` para conectar usuários que tenham contas corporativas ou de estudante ou contas pessoais Microsoft.

O método Configure() contém dois métodos importantes, app.UseAuthentication() e app.UseAuthorization(), que habilitam a funcionalidade nomeada:

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

Como proteger um controlador, um método do controlador ou uma página Razor

Um controlador ou métodos do controlador podem ser protegidos pelo uso do atributo [Authorize]. Esse atributo restringe o acesso ao controlador ou aos métodos permitindo apenas usuários autenticados. Um desafio de autenticação poderá ser iniciado para acessar o controlador se um usuário não estiver autenticado.

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

Validação do escopo no controlador

O código na API verifica se os escopos necessários estão no token usando HttpContext.VerifyUserHasAnyAcceptedScope> (scopeRequiredByApi);:

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        // The web API will only accept tokens 1) for users, and 2) having the "access_as_user" scope for this API
        static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

            // some code here
        }
    }
}

Ajuda e suporte

Se precisar de ajuda, quiser relatar um problema ou desejar saber mais sobre as opções de suporte, confira Ajuda e suporte para desenvolvedores.

Próximas etapas

O repositório GitHub a seguir contém as instruções de exemplo de código da API Web do ASP.NET Core e mais exemplos que mostram como obter o seguinte:

Adicionar a autenticação a uma nova API Web ASP.NET Core.
Chamar a API Web em um aplicativo da área de trabalho.
Chamar APIs downstream como o Microsoft Graph e outras APIs da Microsoft.

Tutoriais da API Web ASP.NET Core no GitHub

Compartilhar via