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

  • Artigo

Bem-vindo! Esta provavelmente não é a página que você estava esperando. Enquanto trabalhamos em uma correção, este link deve levá-lo ao artigo certo:

Guia de início rápido: chame uma API Web do ASP.NET Core protegida pela plataforma de identidade da Microsoft

Pedimos desculpas pelo inconveniente e agradecemos a sua paciência enquanto trabalhamos para resolver este problema.

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

Pré-requisitos

Passo 1: Registar a candidatura

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

  1. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Aplicativos.
  2. Navegue até Registros do aplicativo Identity>Applications>.
  3. Selecione Novo registo.
  4. Em Nome, insira um nome para o aplicativo. Por exemplo, digite AspNetCoreWebApi-Quickstart. Os usuários do aplicativo verão esse nome e poderão ser alterados posteriormente.
  5. Selecione Registar.
  6. Em Gerenciar, selecione Expor uma API>Adicionar um escopo. Para URI de 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 utilizadores
  • Nome de exibição do 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 utilizador: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
  • Estado: Ativado
  1. Selecione Adicionar escopo para concluir a adição de escopo.

Etapa 2: Baixe o projeto ASP.NET Core

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

Nota

O exemplo de código atualmente tem como alvo o ASP.NET Core 3.1. O exemplo pode ser atualizado para usar o .NET Core 6.0 e é abordado nas seguintes etapas: Atualize 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 ASP.NET Core

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

  1. 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 para C:\Azure-Samples.

  2. Abra a solução na pasta webapi no editor de códigos.

  3. 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 é o ID do aplicativo (cliente) para o aplicativo registrado.
    • Substitua Enter_the_Tenant_Info_Here por uma das seguintes opções:
      • Se o aplicativo oferecer suporte a Contas somente neste diretório organizacional, substitua esse valor pelo ID do diretório (locatário) (um GUID) ou nome do locatário (por exemplo, contoso.onmicrosoft.com). O ID do diretório (locatário) pode ser encontrado na página Visão geral do aplicativo.
      • Se o aplicativo oferecer suporte a Contas em qualquer diretório organizacional, substitua esse valor por organizations.
      • Se a aplicação suportar Todos os utilizadores da conta Microsoft, deixe este valor como common.

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

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

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

  1. Abra webapi.csproj
  2. Remova a seguinte linha:
<TargetFramework>netcoreapp3.1</TargetFramework>
  1. Adicione a seguinte linha em seu lugar:
<TargetFramework>netcoreapp6.0</TargetFramework>

Esta etapa garantirá que o exemplo tenha como alvo a estrutura do .NET Core 6.0.

Etapa 5: Executar o exemplo

  1. Abra um terminal e altere o diretório para a pasta do projeto.

    cd webapi

  2. Execute o seguinte comando para criar a solução:

dotnet run

Se a compilação tiver sido bem-sucedida, 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 funciona a amostra

Classe de inicialização

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

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

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

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

appsettings.json chave Description
ClientId ID da aplicação (cliente) da aplicação registada.
Instance Ponto de extremidade do serviço de token de segurança (STS) para o usuário autenticar. Esse valor normalmente https://login.microsoftonline.com/é , indicando a nuvem pública do Azure.
TenantId Nome do seu inquilino ou respetivo ID de inquilino (um GUID) ou para iniciar sessão em utilizadores com contas escolares ou profissionais ou common contas pessoais da Microsoft.

O Configure() método contém dois métodos app.UseAuthentication() importantes e app.UseAuthorization(), que habilitam sua 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
}

Protegendo um controlador, um método de controlador ou uma página Razor

Um controlador ou métodos de controlador podem ser protegidos usando o [Authorize] atributo. Este atributo restringe o acesso ao controlador ou métodos, permitindo apenas usuários autenticados. Um desafio de autenticação pode ser iniciado para acessar o controlador se o usuário não estiver autenticado.

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

Validação do âmbito no responsável pelo tratamento

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 comunicar um problema ou quiser saber mais sobre as suas opções de suporte, consulte Ajuda e suporte para programadores.

Próximos passos

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

  • Adicione autenticação a uma nova API Web ASP.NET Core.
  • Chame a API da Web a partir de um aplicativo de desktop.
  • Chame APIs downstream, como o Microsoft Graph e outras APIs da Microsoft.

ASP.NET Tutoriais da API Web Core no GitHub