Quickstart: Proteja uma API web core ASP.NET com a plataforma de identidade microsoft

Neste quickstart, você descarrega uma amostra de código API web ASP.NET e revê a forma como restringe o acesso de recursos apenas a contas autorizadas. A amostra suporta a autorização de contas e contas pessoais da Microsoft em qualquer organização do Azure Ative Directory (Azure AD).

Pré-requisitos

Passo 1: Registar o pedido

Em primeiro lugar, registe a API web no seu inquilino AZure AD e adicione um âmbito seguindo estes passos:

  1. Inicie sessão no portal do Azure.
  2. Se tiver acesso a vários inquilinos, utilize o filtro de subscrição Diretório + no menu superior para selecionar o inquilino no qual pretende registar uma candidatura.
  3. Procure e selecione Azure Active Directory.
  4. Em Gestão, selecione registos de aplicações > Novo registo.
  5. Para nome, insira um nome para a sua candidatura. Por exemplo, insira AspNetCoreWebApi-Quickstart. Os utilizadores da sua aplicação verão este nome e poderão alterá-lo mais tarde.
  6. Selecione Registar.
  7. Em Gestão, selecione Expor uma API Adicione um > âmbito. Para iD uri de aplicação, aceite o padrão selecionando Save and continue, e, em seguida, insira os seguintes detalhes:
    • Nome do âmbito:access_as_user
    • Quem pode consentir?: Administradores e utilizadores
    • Nome do exposição de consentimento de administração:Access AspNetCoreWebApi-Quickstart
    • Descrição do consentimento da administração: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
    • Nome de visualização do consentimento do utilizador:Access AspNetCoreWebApi-Quickstart
    • Descrição do consentimento do utilizador: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
    • Estado: Habilitado
  8. Selecione Adicionar âmbito para completar a adição de âmbito.

Passo 2: Descarregue o projeto ASP.NET Core

Dica

Para evitar erros causados por limitações de comprimento do caminho no Windows, recomendamos extrair o arquivo ou clonar o repositório para um diretório perto da raiz da sua unidade.

Passo 3: Configurar o projeto ASP.NET Core

Neste passo, configuure o código de amostra para trabalhar com o registo de aplicações que criou anteriormente.

  1. Extraia o arquivo .zip numa pasta perto da raiz da sua unidade. Por exemplo, extrair em C:\Azure-Samples.

    Recomendamos extrair o arquivo num diretório perto da raiz da sua unidade para evitar erros causados por limitações de comprimento do caminho no Windows.

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

  3. Abra a appsettings.jsno ficheiro e modifique o seguinte código:

    "ClientId": "Enter_the_Application_Id_here",
    "TenantId": "Enter_the_Tenant_Info_Here"
    
    • Enter_the_Application_Id_hereSubstitua-se pelo ID de aplicação (cliente) da aplicação que registou no portal Azure. Pode encontrar o ID da aplicação (cliente) na página geral da aplicação.
    • Substitua Enter_the_Tenant_Info_Here por uma das seguintes:
      • Se a sua candidatura apoiar apenas neste diretório organizacional, substitua este valor pelo ID do diretório (inquilino) (um GUIADO) ou nome de inquilino (por exemplo, contoso.onmicrosoft.com ). Pode encontrar o ID do diretório (inquilino) na página geral da aplicação.
      • Se a sua aplicação suportar contas em qualquer diretório organizacional, substitua este valor por organizations .
      • Se a sua aplicação suportar todos os utilizadores da conta microsoft, deixe este valor como common .

Para este arranque rápido, não altere quaisquer outros valores no appsettings.jsno ficheiro.

Como funciona a amostra

A API web recebe um símbolo de uma aplicação do cliente, e o código na API web valida o token. Este cenário é explicado mais detalhadamente em Cenário: API web protegida.

Classe de arranque

O middleware Microsoft.AspNetCore.Authentication utiliza uma Startup classe executada quando o processo de hospedagem começa. No seu ConfigureServices método, o AddMicrosoftIdentityWebApi método de extensão fornecido pelo 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 a autenticação baseada em JwtBearer.

A linha que contém .AddMicrosoftIdentityWebApi adiciona a autorização da plataforma de identidade da Microsoft à sua API web. Em seguida, é configurado para validar fichas de acesso emitidas pela plataforma de identidade da Microsoft com base nas informações AzureAD na secção doappsettings.js no ficheiro de configuração:

appsettings.jsna chave Description
ClientId Identificação da aplicação (cliente) da aplicação registada no portal Azure.
Instance Serviço de ficha de segurança (STS) para o utilizador autenticar. Este valor é tipicamente https://login.microsoftonline.com/ , indicando a nuvem pública Azure.
TenantId Nome do seu inquilino ou identificação do seu inquilino (um GUID), ou common para assinar em utilizadores com contas de trabalho ou escola ou contas pessoais da Microsoft.

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

Proteger um controlador, um método de controlador ou uma página razor

Pode proteger um controlador ou métodos de controlador utilizando o [Authorize] atributo. Este atributo restringe o acesso ao controlador ou métodos, permitindo apenas utilizadores autenticados. Pode iniciar-se um desafio de autenticação no acesso ao controlador se o utilizador não for autenticado.

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

Validação do âmbito no controlador

O código da API verifica que os âmbitos necessários estão no símbolo através da HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi); utilização:

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, quer reportar um problema ou quer saber sobre as suas opções de suporte, consulte ajuda e suporte para programadores.

Passos seguintes

O repositório GitHub que contém esta amostra de código API web core ASP.NET inclui instruções e mais amostras de código que mostram como:

  • Adicione a autenticação a um novo ASP.NET Core web API.
  • Ligue para a API web a partir de uma aplicação de ambiente de trabalho.
  • Ligue para APIs a jusante como o Microsoft Graph e outros APIs da Microsoft.