Habilitar a autenticação em sua própria API Web usando o Azure AD B2C

Importante

A partir de 1º de maio de 2025, o Azure AD B2C não estará mais disponível para compra para novos clientes. Saiba mais em nossas perguntas frequentes.

Para autorizar o acesso a uma API Web, você só pode atender a solicitações que incluem um token de acesso válido que o Azure Active Directory B2C (Azure AD B2C) emite. 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 estarão autorizados a chamar os endpoints da sua API Web.

Pré-requisitos

Antes de começar, leia um dos artigos a seguir, que abordam 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 SPA (aplicativo de página única) de exemplo

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. Ele autentica usuários com o 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. Ele 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. O sistema valida o token.

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

4. Ele lê as declarações codificadas no token (opcional).

5. Ele responde à solicitação HTTP.

Visão geral do registro do aplicativo

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

• O registro de aplicativos Web, móveis ou SPA habilita seu aplicativo a autenticar-se com o Azure AD B2C. O processo de registro do aplicativo gera uma ID do aplicativo, também conhecida como ID do cliente, que identifica exclusivamente seu aplicativo (por exemplo, ID do aplicativo: 1).

• O registro da API Web permite que seu 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 ao aplicativo (ID do aplicativo: 1) permissões para os escopos da API Web (ID do aplicativo: 2).

Os registros de aplicativo e a arquitetura do aplicativo sã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

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

Node.js

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

Etapa 1: Criar uma API Web protegida

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

ASP.NET Core

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

dotnet new webapi -o TodoList
cd TodoList
code . 

Quando você 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. Este 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 do 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 obter mais informações, examine 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 de agente de solicitação HTTP para 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 Startup.cs e, no início da classe, adicione as seguintes using declarações:

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 trecho 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, imediatamente após a linha de código app.UseRouting();, adicione o seguinte trecho de código:

app.UseAuthentication();

Após a alteração, seu código deve se parecer com o 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 seguinte código JavaScript 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 endpoints à API Web:

• Ponto de extremidade /public anônimo. Esse ponto de extremidade retorna a data e a hora atuais. Use-a 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 adicione-o ao 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

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

// 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 adicione-o ao 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 HelloController controlador é decorado com o AuthorizeAttribute, que limita o acesso somente 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 corretos. 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 é chamada com os escopos corretos. 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 snippet JSON a seguir ao arquivo appsettings.json .

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

Node.js

Adicione o seguinte código JavaScript ao arquivo app.js . É possível configurar os endpoints HTTP e HTTPS para a aplicação Node.

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

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

Etapa 6: Configurar a API Web

Adicione configurações a um arquivo de configuração. O arquivo contém informações sobre o 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	Exemplo	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	A ID do aplicativo de API Web. No diagrama anterior, é 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 de usuário ou a política personalizada. Para saber como obter o fluxo ou a política do usuário, consulte Pré-requisitos.

Node.js

Na pasta raiz do projeto, crie um arquivo config.json e adicione-o ao 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	nomeDoInquilino	Nome de tenant/nome de domínio do Azure AD B2C (por exemplo, contoso.onmicrosoft.com).
credenciais	identificador do cliente	A ID do aplicativo de API Web. No diagrama anterior, é 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 ID do inquilino do Azure AD B2C.
políticas	Nome da política	Os fluxos de usuário ou a política personalizada. Para saber como obter o fluxo ou a política do usuário, consulte Pré-requisitos.
recurso	âmbito	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 de ambiente do 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 node app.js comando.

Dica

Como alternativa, para executar o dotnet run comando, você pode usar o depurador do Visual Studio Code. O depurador interno do 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 exibido, 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 node app.js comando.

Dica

Como alternativa, para executar o node app.js comando, use o depurador do Visual Studio Code. O depurador interno do 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 exibido, juntamente com a data e a hora atuais.

Etapa 8: Chamar a API Web do seu aplicativo

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

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

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

Conteúdo relacionado

Obtenha o exemplo completo no GitHub:

ASP.NET Core

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

Node.js

• Obtenha a API Web usando a biblioteca dePassport.js.