Habilitar a autenticação na sua API Web usando o Azure AD B2C

Para autorizar o acesso a uma API Web, atenda apenas às solicitações que incluam um token de acesso válido emitido pelo Azure AD B2C (Azure Active Directory B2C). Este artigo mostra como habilitar a autorização do Azure AD B2C para sua API Web. Depois de concluir as etapas neste artigo, somente os usuários que obtiverem um token de acesso válido serão autorizados a chamar os pontos de extremidade da sua API Web.

Pré-requisitos

Antes de começar, leia um dos artigos a seguir, que discutem como configurar a autenticação para aplicativos que chamam APIs Web. Em seguida, siga as etapas neste artigo para substituir a API Web de exemplo por sua própria API Web.

• Configurar a autenticação em um aplicativo ASP.NET Core de exemplo
• Configurar a autenticação em um aplicativo de página única (SPA) de amostra

Visão geral

A autenticação baseada em token garante que as solicitações a uma API Web incluam um token de acesso válido.

O aplicativo conclui as seguintes etapas:

1. Autentica usuários no Azure AD B2C.

2. Adquire um token de acesso com as permissões necessárias (escopos) para o ponto de extremidade da API Web.

3. Passa o token de acesso como um token de portador no cabeçalho de autenticação da solicitação HTTP usando este formato:

   Authorization: Bearer <access token>
   

A API Web conclui as seguintes etapas:

1. Lê o token de portador do cabeçalho de autorização na solicitação HTTP.

2. Valida o token.

3. Valida as permissões (escopos) no token.

4. Lê as declarações que estão codificadas no token (opcional).

5. Responde à solicitação HTTP.

Visão geral do registro do aplicativo

Para permitir que o seu aplicativo entre com o Azure AD B2C e chame uma API Web, registre dois aplicativos no diretório do Azure AD B2C.

• O registro de aplicativo Web, aplicativo móvel ou SPA permite que o seu aplicativo entre com o Azure AD B2C. O processo de registro de aplicativo gera uma ID de aplicativo, também conhecida como ID do cliente, que identifica o aplicativo de modo exclusivo (por exemplo, ID do Aplicativo: 1).

• O registro da API Web permite que o aplicativo chame uma API Web protegida. O registro expõe as permissões da API Web (escopos). O processo de registro do aplicativo gera uma ID do aplicativo que identifica exclusivamente sua API Web (por exemplo, ID do Aplicativo: 2). Conceda permissões ao aplicativo (ID do aplicativo: 1) para os escopos da API Web (ID do aplicativo: 2).

Os registros e a arquitetura do aplicativo estão descritos no diagrama a seguir:

Preparar seu ambiente de desenvolvimento

Nas próximas seções, você criará um novo projeto de API Web. Selecione sua linguagem de programação, ASP.NET Core ou Node.js. Verifique se você tem um computador que está executando um dos seguintes softwares:

ASP.NET Core

• Visual Studio Code
• C# para o Visual Studio Code (versão mais recente)
• .NET 5.0 SDK

Node.js

• Visual Studio Code ou outro editor de código
• Runtime do Node.js

Etapa 1: criar uma API Web protegida

Criar um novo projeto de API Web. Primeiro selecione a linguagem de programação que você deseja usar, ASP.NET Core ou Node.js.

ASP.NET Core

Use o comando dotnet new. O comando dotnet new cria uma nova pasta chamada ToDoList com os ativos do projeto da API Web. Abra o diretório, e em seguida abra o Visual Studio Code.

dotnet new webapi -o TodoList
cd TodoList
code . 

Quando for solicitado a "adicionar ativos necessários ao projeto", selecione Sim.

Node.js

Use o Expresso para o Node.js para criar uma API Web. Para criar uma API Web, faça o seguinte:

1. Crie uma nova pasta chamada ToDoList.
2. Na pasta ToDoList, crie um arquivo chamado app.js.
3. Em um shell de comando, execute npm init -y. Esse comando cria um arquivo package.json padrão para seu projeto Node.js.
4. No shell de comando, execute npm install express. Esse comando instala a estrutura Express.

Etapa 2: instalar as dependências

Adicione a biblioteca de autenticação ao seu projeto de API Web. A biblioteca de autenticação analisa o cabeçalho de autenticação HTTP, valida o token e extrai declarações. Para mais informações, revise a documentação da biblioteca.

ASP.NET Core

Para adicionar a biblioteca de autenticação, instale o pacote executando o seguinte comando:

dotnet add package Microsoft.Identity.Web

Node.js

Para adicionar a biblioteca de autenticação, instale os pacotes executando o seguinte comando:

npm install passport
npm install passport-azure-ad
npm install morgan

O pacote morgan é um middleware do agente de solicitação HTTP para o Node.js.

Etapa 3: Iniciar a biblioteca de autenticação

Adicione o código necessário para iniciar a biblioteca de autenticação.

ASP.NET Core

Abra o Startup.cs; no início da classe, adicione as seguintes declarações using:

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

Localize a função ConfigureServices(IServiceCollection services). Em seguida, antes da linha de código services.AddControllers();, adicione o seguinte snippet de código:

public void ConfigureServices(IServiceCollection services)
{
    // Adds Microsoft Identity platform (Azure AD B2C) support to protect this Api
    services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
            .AddMicrosoftIdentityWebApi(options =>
    {
        Configuration.Bind("AzureAdB2C", options);

        options.TokenValidationParameters.NameClaimType = "name";
    },
    options => { Configuration.Bind("AzureAdB2C", options); });
    // End of the Microsoft Identity platform block    

    services.AddControllers();
}

Localize a função Configure. Em seguida, logo após a linha de código app.UseRouting();, adicione o seguinte snippet de código:

app.UseAuthentication();

Após a alteração, o código deve ser semelhante ao seguinte snippet:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();

    app.UseRouting();
    
    // Add the following line 
    app.UseAuthentication();
    // End of the block you add
    
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Node.js

Adicione o código JavaScript a seguir ao seu arquivo app.js.

// Import the required libraries
const express = require('express');
const morgan = require('morgan');
const passport = require('passport');
const config = require('./config.json');

// Import the passport Azure AD library
const BearerStrategy = require('passport-azure-ad').BearerStrategy;

// Set the Azure AD B2C options
const options = {
    identityMetadata: `https://${config.credentials.tenantName}.b2clogin.com/${config.credentials.tenantName}.onmicrosoft.com/${config.policies.policyName}/${config.metadata.version}/${config.metadata.discovery}`,
    clientID: config.credentials.clientID,
    audience: config.credentials.clientID,
    issuer: config.credentials.issuer,
    policyName: config.policies.policyName,
    isB2C: config.settings.isB2C,
    scope: config.resource.scope,
    validateIssuer: config.settings.validateIssuer,
    loggingLevel: config.settings.loggingLevel,
    passReqToCallback: config.settings.passReqToCallback
}

// Instantiate the passport Azure AD library with the Azure AD B2C options
const bearerStrategy = new BearerStrategy(options, (token, done) => {
        // Send user info using the second argument
        done(null, { }, token);
    }
);

// Use the required libraries
const app = express();

app.use(morgan('dev'));

app.use(passport.initialize());

passport.use(bearerStrategy);

//enable CORS (for testing only -remove in production/deployment)
app.use((req, res, next) => {
    res.header('Access-Control-Allow-Origin', '*');
    res.header('Access-Control-Allow-Headers', 'Authorization, Origin, X-Requested-With, Content-Type, Accept');
    next();
});

Etapa 4: adicionar os pontos de extremidade

Adicione dois pontos de extremidade à sua API Web:

• Ponto de extremidade /public anônimo. Esse ponto de extremidade retorna a data e a hora atuais. Use-o para depurar sua API Web com chamadas anônimas.
• Ponto de extremidade /hello protegido. Esse ponto de extremidade retorna o valor da declaração name dentro do token de acesso.

Para adicionar o ponto de extremidade anônimo:

ASP.NET Core

Na pasta /Controllers, adicione um arquivo PublicController.cs e, em seguida, adicione a ele o seguinte snippet de código:

using System;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;

namespace TodoList.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class PublicController : ControllerBase
    {
        private readonly ILogger<PublicController> _logger;

        public PublicController(ILogger<PublicController> logger)
        {
            _logger = logger;
        }

        [HttpGet]
        public ActionResult Get()
        {
            return Ok( new {date = DateTime.UtcNow.ToString()});
        }
    }
}

Node.js

Adicione o código JavaScript a seguir ao seu arquivo app.js:

// API anonymous endpoint
app.get('/public', (req, res) => res.send( {'date': new Date() } ));

Para adicionar o ponto de extremidade protegido:

ASP.NET Core

Na pasta /Controllers, adicione um arquivo HelloController.cs e, em seguida, adicione a ele o seguinte código:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Microsoft.Identity.Web.Resource;

namespace TodoList.Controllers
{
    [Authorize]
    [RequiredScope("tasks.read")]
    [ApiController]
    [Route("[controller]")]
    public class HelloController : ControllerBase
    {

        private readonly ILogger<HelloController> _logger;
        private readonly IHttpContextAccessor _contextAccessor;

        public HelloController(ILogger<HelloController> logger, IHttpContextAccessor contextAccessor)
        {
            _logger = logger;
            _contextAccessor = contextAccessor;
        }

        [HttpGet]
        public ActionResult Get()
        {
            return Ok( new { name = User.Identity.Name});
        }
    }
}

O controlador HelloController é decorado com o AuthorizeAttribute, que limita o acesso apenas a usuários autenticados.

O controlador também é decorado com o [RequiredScope("tasks.read")]. O RequiredScopeAttribute verifica se a API Web é chamada com os escopos certos, tasks.read.

Node.js

No arquivo app.js, adicione o seguinte código JavaScript:

// API protected endpoint
app.get('/hello',
    passport.authenticate('oauth-bearer', {session: false}),
    (req, res) => {
        console.log('Validated claims: ', req.authInfo);
        
        // Service relies on the name claim.  
        res.status(200).json({'name': req.authInfo['name']});
    }
);

O ponto de extremidade /hello primeiro chama a função passport.authenticate(). A função de autenticação limita o acesso somente a usuários autenticados.

A função de autenticação também verifica se a API Web está sendo chamada com os escopos certos. Os escopos permitidos estão localizados no arquivo de configuração.

Etapa 5: Configurar o servidor Web

Em um ambiente de desenvolvimento, defina a API Web para escutar o número da porta das solicitações HTTP ou HTTPS de entrada. Neste exemplo, use a porta HTTP 6000 e a porta HTTPS 6001. O URI base da API Web será http://localhost:6000 para HTTP e https://localhost:6001 para HTTPS.

ASP.NET Core

Adicione o arquivo JSON seguinte ao arquivo appsettings.json.

"Kestrel": {
    "EndPoints": {
      "Http": {
        "Url": "http://localhost:6000"
      },
      "Https": {
         "Url": "https://localhost:6001"   
        }
    }
  }

Node.js

Adicione o código JavaScript seguinte ao arquivo app.js. É possível configurar pontos de extremidade HTTP e HTTPS para o aplicativo Node.

// Starts listening on port 6000
const port = process.env.PORT || 6000;

app.listen(port, () => {
    console.log('Listening on port ' + port);
});

Etapa 6: Configurar o API Web

Adicione configurações a um arquivo de configuração. Esse arquivo contém informações sobre seu provedor de identidade do Azure AD B2C. O aplicativo de API Web usa essas informações para validar o token de acesso que o aplicativo Web passa como um token de portador.

ASP.NET Core

Na pasta raiz do projeto, abra o arquivo appsettings.json e adicione as seguintes configurações:

{
  "AzureAdB2C": {
    "Instance": "https://contoso.b2clogin.com",
    "Domain": "contoso.onmicrosoft.com",
    "ClientId": "<web-api-app-application-id>",
    "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
    "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
  },
  // More settings here
}

No arquivo appsettings.json, atualize as seguintes propriedades:

Seção	Chave	Valor
AzureAdB2C	Instância	A primeira parte do nome do locatário do Azure Active Directory B2C (por exemplo, https://contoso.b2clogin.com).
AzureAdB2C	Domínio	O nome de locatário completo do locatário do Azure Active Directory B2C (por exemplo, contoso.onmicrosoft.com).
AzureAdB2C	ClientId	O ID do aplicativo API Web. No diagrama acima, é o aplicativo com a ID do aplicativo: 2. Para saber como obter a ID de registro do aplicativo de API Web, consulte Pré-requisitos.
AzureAdB2C	SignUpSignInPolicyId	Os fluxos dos usuários, ou a política personalizada. Para saber como obter o fluxo ou a política de usuário, consulte Pré-requisitos.

Node.js

Na pasta raiz do projeto, crie um arquivo config.json e adicione a ele o seguinte snippet JSON:

{
    "credentials": {
        "tenantName": "<your-tenant-name>.onmicrosoft.com",
        "clientID": "<your-webapi-application-ID>",
        "issuer": "https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/"
    },
    "policies": {
        "policyName": "b2c_1_susi"
    },
    "resource": {
        "scope": ["tasks.read"]
    },
    "metadata": {
        "discovery": ".well-known/openid-configuration",
        "version": "v2.0"
    },
    "settings": {
        "isB2C": true,
        "validateIssuer": true,
        "passReqToCallback": false,
        "loggingLevel": "info"
    }
}

No arquivo config.json, atualize as seguintes propriedades:

Seção	Chave	Valor
credenciais	tenantName	O nome de locatário/nome de domínio do Azure AD B2C (por exemplo, contoso.onmicrosoft.com).
credenciais	clientID	O ID do aplicativo API Web. No diagrama acima, é o aplicativo com a ID do aplicativo: 2. Para saber como obter a ID de registro do aplicativo de API Web, consulte Pré-requisitos.
credenciais	emissor	O valor da declaração iss do emissor do token. Por padrão, o Azure AD B2C retorna o token no seguinte formato: https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/. Substitua <your-tenant-name> pela primeira parte do nome do locatário do Azure AD B2C. Substitua <your-tenant-ID> pelo nome do seu locatário do Azure AD B2C.
políticas	policyName	Os fluxos dos usuários, ou a política personalizada. Para saber como obter o fluxo de usuário ou a política, consulte Pré-requisitos.
recurso	scope	Os escopos do registro do aplicativo da API Web. Para saber como obter o escopo da API Web, consulte Pré-requisitos.

Etapa 7: Executar e testar a API Web

Por fim, execute a API Web com as configurações do seu ambiente Azure AD B2C.

ASP.NET Core

No shell de comando, inicie o aplicativo Web executando o seguinte comando:

 dotnet run

Você deverá ver a saída a seguir, o que significa que seu aplicativo está em execução e pronto para receber solicitações.

Now listening on: http://localhost:6000

Para interromper o programa, no shell de comando, selecione Ctrl+C. Você pode executar novamente o aplicativo usando o comando node app.js.

Dica

Como alternativa para executar o comando dotnet run, você pode usar o depurador do Visual Studio Code. O depurador integrado ao Visual Studio Code ajuda a acelerar o loop de edição, compilação e depuração.

Abra um navegador e acesse http://localhost:6000/public. Na janela do navegador, você deverá ver o texto a seguir, juntamente com a data e a hora atuais.

Node.js

No shell de comando, inicie o aplicativo Web executando o seguinte comando:

node app.js

Você deverá ver a saída a seguir, o que significa que seu aplicativo está em execução e pronto para receber solicitações.

Example app listening on port 6000!

Para interromper o programa, no shell de comando, selecione Ctrl+C. Você pode executar novamente o aplicativo usando o comando node app.js.

Dica

Como alternativa para executar o comando node app.js, você pode usar o depurador do Visual Studio Code. O depurador integrado ao Visual Studio Code ajuda a acelerar o loop de edição, compilação e depuração.

Abra um navegador e acesse http://localhost:6000/public. Na janela do navegador, você deverá ver o texto a seguir, juntamente com a data e a hora atuais.

Etapa 8: Chamar a API Web do seu aplicativo

Tente chamar o ponto de extremidade de API Web protegido sem um token de acesso. Abra um navegador e acesse http://localhost:6000/hello. A API retornará uma mensagem de erro HTTP não autorizada, confirmando que a API Web está protegida com um token de portador.

Continue a configurar seu aplicativo para chamar a API Web. Para obter diretrizes, confira a seção Pré-requisitos.

Assista a este vídeo para saber mais sobre algumas melhores práticas ao integrar o Azure AD B2C com uma API.

Próximas etapas

Obter o exemplo completo no GitHub:

ASP.NET Core

• Obter a API Web usando a biblioteca de identidade da Microsoft.

Node.js

• Obter a API Web usando a biblioteca Passport.js.