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 nas nossas Perguntas Frequentes.

Para autorizar o acesso a uma API Web, você pode atender somente solicitações que incluam um token de acesso válido que o Azure Ative 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 utilizadores que obtiverem um token de acesso válido terão autorização para aceder aos seus endpoints da API web.

Pré-requisitos

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

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

Visão geral

A autenticação baseada em tokens garante que as solicitações a uma API da 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 (âmbitos) necessárias para o endpoint 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 da Web conclui as seguintes etapas:

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

2. Ele valida o token.

3. Ele valida as permissões (escopos) no token.

4. Ele lê as declarações que são 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 registo da aplicação web, móvel ou SPA permite que a aplicação inicie sessão 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 da Web permite que seu aplicativo chame uma API da Web protegida. O registo expõe as permissões da API web (escopos). O processo de registro do aplicativo gera uma ID de aplicativo, que identifica exclusivamente sua API da Web (por exemplo, ID de aplicativo: 2). Conceda ao seu aplicativo (ID do aplicativo: 1) permissões para os escopos da API da Web (ID do aplicativo: 2).

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

Prepare seu ambiente de desenvolvimento

Nas próximas seções, você cria um novo projeto de API da Web. Selecione sua linguagem de programação, ASP.NET Core ou Node.js. Certifique-se de que tem um computador com um dos seguintes softwares:

ASP.NET Núcleo

• 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
• Node.js tempo de execução

Etapa 1: Criar uma API da Web protegida

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

ASP.NET Núcleo

Use o comando dotnet new. O dotnet new comando cria uma nova pasta chamada TodoList com os ativos do projeto da API da 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 os ativos necessários ao projeto", selecione Sim.

Node.js

Use Express for Node.js para criar uma API web. Para criar uma API da 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 depackage.json padrão para seu projeto Node.js.
4. Na shell de comandos, execute npm install express. Este comando instala a estrutura Express.

Etapa 2: Instalar as dependências

Adicione a biblioteca de autenticação ao seu projeto de API da 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, consulte a documentação da biblioteca.

ASP.NET Núcleo

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 registador de pedidos 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 Núcleo

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

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

Encontre a função ConfigureServices(IServiceCollection services) Em seguida, antes da linha de código services.AddControllers();, adicione o seguinte segmento 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();
}

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

app.UseAuthentication();

Após a alteração, seu código deve se parecer com o seguinte trecho:

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 ficheiro 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 endpoints

Adicione dois pontos de extremidade à sua API da Web:

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

Para adicionar o ponto de extremidade anônimo:

ASP.NET Núcleo

Na pasta /Controllers , adicione um arquivo PublicController.cs e adicione-o ao seguinte trecho 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 Núcleo

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 apenas a usuários autenticados.

O controlador também está decorado com o [RequiredScope("tasks.read")]. O RequiredScopeAttribute verifica se a API da 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 /hello ponto de extremidade primeiro chama a passport.authenticate() função. A função de autenticação limita o acesso apenas a utilizadores autenticados.

A função de autenticação também verifica se a API da 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 da Web para escutar o número da porta de solicitações HTTP ou HTTPS recebidas. Neste exemplo, use a porta HTTP 6000 e a porta HTTPS 6001. O URI base da API da Web será http://localhost:6000 para HTTP e https://localhost:6001 HTTPS.

ASP.NET Núcleo

Adicione o seguinte trecho JSON 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 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 a API da Web

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

ASP.NET Núcleo

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 inquilino do Azure AD B2C (por exemplo, https://contoso.b2clogin.com).
AzureAdB2C	Domínio	O nome completo do inquilino do Azure AD B2C (por exemplo, ).
AzureAdB2C	ID do Cliente	O ID do aplicativo de API da Web. No diagrama anterior, é o aplicativo com App ID: 2. Para saber como obter seu ID de registro de aplicativo de API da Web, consulte Pré-requisitos.
AzureAdB2C	IdPolíticaRegistoInícioSessão	Os fluxos do utilizador ou política personalizada. Para saber como obter seu fluxo de usuário ou política, consulte Pré-requisitos.

Node.js

Na pasta raiz do projeto, crie um arquivo config.json e adicione-o ao seguinte trecho 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	Seu nome de locatário/nome de domínio do Azure AD B2C (por exemplo, contoso.onmicrosoft.com).
Credenciais	ID do cliente	O ID do aplicativo de API da Web. No diagrama anterior, é o aplicativo com App ID: 2. Para saber como obter seu ID de registro de aplicativo de API da Web, consulte Pré-requisitos.
Credenciais	emitente	O valor da declaração do emissor do token iss. 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> pela sua ID de locatário do Azure AD B2C.
Políticas	nome_da_política	Os fluxos do utilizador ou política personalizada. Para saber como obter seu fluxo de usuário ou política, consulte Pré-requisitos.
recurso	Âmbito de aplicação	Os escopos do registro do seu aplicativo de API da Web. Para saber como obter o escopo da API da Web, consulte Pré-requisitos.

Etapa 7: Executar e testar a API da Web

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

ASP.NET Núcleo

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

 dotnet run

Você 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 parar o programa, na linha de comando, selecione Ctrl+C. Você pode executar novamente o aplicativo usando o node app.js comando.

Sugestão

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

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

Node.js

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

node app.js

Você 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 parar o programa, na linha de comando, selecione Ctrl+C. Você pode executar novamente o aplicativo usando o node app.js comando.

Sugestão

Como alternativa, para executar o node app.js comando, use o depurador de código do Visual Studio. O depurador interno do Visual Studio Code ajuda a acelerar o loop de edição, compilação e depuração.

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

Etapa 8: Chamar a API da Web do seu aplicativo

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

Continue a configurar seu aplicativo para chamar a API da Web. Para obter orientações, 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 Núcleo

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

Node.js

• Obtenha a API da Web usando a bibliotecaPassport.js.