Verificatie inschakelen in uw eigen web-API met behulp van Azure AD B2C

Als u toegang tot een web-API wilt autoriseren, kunt u alleen aanvragen verwerken die een geldig toegangstoken bevatten dat problemen met Azure Active Directory B2C (Azure AD B2C) bevat. In dit artikel wordt beschreven hoe u Azure AD B2C-autorisatie voor uw web-API inschakelt. Nadat u de stappen in dit artikel hebt voltooid, worden alleen gebruikers die een geldig toegangstoken verkrijgen gemachtigd om uw web-API-eindpunten aan te roepen.

Vereisten

Lees voordat u begint een van de volgende artikelen waarin wordt beschreven hoe u verificatie configureert voor apps die web-API's aanroepen. Volg vervolgens de stappen in dit artikel om de voorbeeldweb-API te vervangen door uw eigen web-API.

• Verificatie configureren in een voorbeeld van een ASP.NET Core-toepassing
• Verificatie configureren in een voorbeeldtoepassing met één pagina (SPA)

Overzicht

Verificatie op basis van tokens zorgt ervoor dat aanvragen voor een web-API een geldig toegangstoken bevatten.

De app voert de volgende stappen uit:

1. Gebruikers worden geverifieerd met Azure AD B2C.

2. Er wordt een toegangstoken verkregen met de vereiste machtigingen (bereiken) voor het web-API-eindpunt.

3. Het toegangstoken wordt doorgegeven als een Bearer-token in de verificatieheader van de HTTP-aanvraag met deze indeling:

   Authorization: Bearer <access token>
   

De web-API voert de volgende stappen uit:

1. Het Bearer-token wordt gelezen uit de autorisatieheader in de HTTP-aanvraag.

2. Het token wordt gevalideerd.

3. De machtigingen (bereiken) in het token worden gevalideerd.

4. De claims die zijn gecodeerd in het token worden gelezen (optioneel).

5. Er wordt gereageerd op de HTTP-aanvraag.

Overzicht van app-registratie

Als u wilt dat uw app zich kan aanmelden met Azure AD B2C en een web-API wilt aanroepen, moet u twee toepassingen registreren in de Azure AD B2C-directory.

• Met de registratie van de web-, mobiele of SPA-toepassing kan uw app zich aanmelden met Azure AD B2C. Het app-registratieproces genereert een toepassings-id, ook wel de client-id genoemd, waarmee uw toepassing op unieke wijze wordt aangeduid (bijvoorbeeld app-id: 1).

• Met de registratie van een web-API kan de app een beveiligde web-API aanroepen. De registratie maakt de web-API-machtigingen (bereiken) beschikbaar. Het app-registratieproces genereert een toepassings-id, waarmee uw web-API op unieke wijze wordt aangeduid (bijvoorbeeld app-id: 2). Ken aan uw app (app-id: 1) machtigingen toe voor de web-API-bereiken (app-id: 2).

De toepassingsregistraties en de toepassingsarchitectuur worden beschreven in het volgende diagram:

Uw ontwikkelomgeving voorbereiden

In de volgende secties maakt u een nieuw web-API-project. Selecteer uw programmeertaal, ASP.NET Core of Node.js. Zorg ervoor dat u een computer hebt waarop een van de volgende software wordt uitgevoerd:

ASP.NET Core

• Visual Studio Code
• C# voor Visual Studio Code (nieuwste versie)
• .NET 5.0 SDK

Node.js

• Visual Studio Code of een andere code-editor
• Node.js-runtime

Stap 1: Een beveiligde web-API maken

Maak een nieuw web-API-project. Selecteer eerst de programmeertaal die u wilt gebruiken, ASP.NET Core of Node.js.

ASP.NET Core

Gebruik de opdracht dotnet new. Met de opdracht dotnet new maakt u een nieuwe map met de naam TodoList met de web-API-projectassets. Open de map en open vervolgens Visual Studio Code.

dotnet new webapi -o TodoList
cd TodoList
code . 

Wanneer u wordt gevraagd om vereiste assets aan het project toe te voegen, selecteert u Ja.

Node.js

Gebruik Express om met Node.js een web-API te compileren. Ga als volgt te werk om een web-API te maken:

1. Maak een nieuwe map met de naam TodoList.
2. Maak in de map TodoList een bestand met de naam app.js.
3. Voer in de opdrachtshell npm init -y uit. Met deze opdracht maakt u een package.json-standaardbestand voor uw Node.js-project.
4. Voer in de opdrachtshell npm install express uit. Met deze opdracht wordt het Express-framework geïnstalleerd.

Stap 2: De afhankelijkheden installeren

Voeg de verificatiebibliotheek toe aan uw web-API-project. De verificatiebibliotheek parseert de HTTP-verificatieheader, valideert het token en extraheert claims. Raadpleeg de documentatie voor de bibliotheek voor meer informatie.

ASP.NET Core

Als u de verificatiebibliotheek wilt toevoegen, installeert u het pakket door de volgende opdracht uit te voeren:

dotnet add package Microsoft.Identity.Web

Node.js

Als u de verificatiebibliotheek wilt toevoegen, installeert u de pakketten door de volgende opdracht uit te voeren:

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

Het morgan-pakket is logger-middleware voor HTTP-aanvragen voor Node.js.

Stap 3: De verificatiebibliotheek initiëren

Voeg de benodigde code toe om de verificatiebibliotheek te initiëren.

ASP.NET Core

Open Startup.cs en voeg vervolgens aan het begin van de klasse de volgende using-declaraties toe:

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

Zoek de functie ConfigureServices(IServiceCollection services). Voeg vervolgens vóór de coderegel services.AddControllers(); het volgende codefragment toe:

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();
}

Zoek de functie Configure. Voeg vervolgens direct na de coderegel app.UseRouting(); het volgende codefragment toe:

app.UseAuthentication();

Na de wijziging moet uw code eruitzien als het volgende codefragment:

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

Voeg de volgende JavaScript-code toe aan het bestand 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();
});

Stap 4: De eindpunten toevoegen

Voeg twee eindpunten toe aan uw web-API:

• Anoniem /public-eindpunt. Dit eindpunt retourneert de huidige datum en tijd. Gebruik het om fouten in uw web-API op te sporen met anonieme aanroepen.
• Beveiligd /hello-eindpunt. Dit eindpunt retourneert de waarde van de name-claim in het toegangstoken.

Het anonieme eindpunt toevoegen:

ASP.NET Core

Voeg onder de map /Controllers een PublicController.cs-bestand toe en voeg het toe aan het volgende codefragment:

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

Voeg in het bestand app.js de volgende JavaScript-code toe:

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

Het beveiligde eindpunt toevoegen:

ASP.NET Core

Voeg onder de map /Controllers een HelloController.cs-bestand toe en voeg het toe aan de volgende code:

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});
        }
    }
}

De HelloController-controller is voorzien van AuthorizeAttribute, waardoor de toegang wordt beperkt tot alleen geverifieerde gebruikers.

De controller is ook voorzien van [RequiredScope("tasks.read")]. RequiredScopeAttribute controleert of de web-API wordt aangeroepen met de juiste bereiken, tasks.read.

Node.js

Voeg in het bestand app.js de volgende JavaScript-code toe:

// 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']});
    }
);

Het /hello-eindpunt roept eerst de passport.authenticate()-functie aan. De verificatiefunctie beperkt de toegang tot alleen geverifieerde gebruikers.

De verificatiefunctie controleert ook of de web-API wordt aangeroepen met de juiste bereiken. De toegestane bereiken bevinden zich in het configuratiebestand.

Stap 5: De webserver configureren

Stel in een ontwikkelomgeving de web-API in om te luisteren naar het poortnummer van binnenkomende HTTP- of HTTPS-aanvragen. Gebruik in dit voorbeeld HTTP-poort 6000 en HTTPS-poort 6001. De basis-URI van de web-API is http://localhost:6000 voor HTTP en https://localhost:6001 voor HTTPS.

ASP.NET Core

Voeg het volgende JSON-fragment toe aan het bestand appsettings.json.

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

Node.js

Voeg de volgende JavaScript-code toe aan het bestand app.js. Het is mogelijk om HTTP- en HTTPS-eindpunten in te stellen voor de Node-toepassing.

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

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

Stap 6: De web-API configureren

Voeg configuraties toe aan een configuratiebestand. Het bestand bevat informatie over uw Azure AD B2C-id-provider. De web-API-app gebruikt deze informatie om het toegangstoken te valideren dat de web-app als Bearer-token doorgeeft.

ASP.NET Core

Open in de hoofdmap van het project het bestand appsettings.json en voeg vervolgens de volgende instellingen toe:

{
  "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
}

Werk in het bestand appsettings.json de volgende eigenschappen bij:

Sectie	Sleutel	Weergegeven als
AzureAdB2C	Exemplaar	Het eerste deel van uw Azure AD B2C-tenantnaam (bijvoorbeeld https://contoso.b2clogin.com).
AzureAdB2C	Domain	De volledige tenantnaam van uw Azure AD B2C-tenant (bijvoorbeeld contoso.onmicrosoft.com).
AzureAdB2C	ClientId	De id van de web-API-toepassing. In het voorgaande diagram is het de toepassing met app-id: 2. Zie Vereisten voor meer informatie over het ophalen van de registratie-id van uw web-API-toepassing.
AzureAdB2C	SignUpSignInPolicyId	De gebruikersstromen of het aangepaste beleid. Zie Vereisten voor meer informatie over het verkrijgen van uw gebruikersstroom of beleid.

Node.js

Maak onder de hoofdmap van het project een config.json-bestand en voeg het toe aan het volgende JSON-fragment:

{
    "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"
    }
}

Werk in het bestand config.json de volgende eigenschappen bij:

Sectie	Sleutel	Weergegeven als
aanmeldingsgegevens	tenantName	Uw Azure AD B2C-tenantnaam /domeinnaam (bijvoorbeeld contoso.onmicrosoft.com).
aanmeldingsgegevens	clientid	De id van de web-API-toepassing. In het voorgaande diagram is het de toepassing met app-id: 2. Zie Vereisten voor meer informatie over het ophalen van de registratie-id van uw web-API-toepassing.
aanmeldingsgegevens	Uitgevende instelling	De iss-claimwaarde van de tokenverlener. Standaard retourneert Azure AD B2C het token in de volgende indeling: https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/. Vervang <your-tenant-name> door het eerste deel van uw Azure AD B2C-tenantnaam. Vervang <your-tenant-ID> door uw Azure AD B2C-tenant-id.
policies	policyName	De gebruikersstromen of het aangepaste beleid. Zie Vereisten voor meer informatie over het verkrijgen van uw gebruikersstroom of beleid.
resource	bereik	De bereiken van de registratie van uw web-API-toepassing. Zie Vereisten voor meer informatie over het verkrijgen van uw web-API-bereik.

Stap 7: De web-API uitvoeren en testen

Voer ten slotte de web-API uit met uw Azure AD B2C-omgevingsinstellingen.

ASP.NET Core

Start de web-app in de opdrachtshell door de volgende opdracht uit te voeren:

 dotnet run

U ziet nu de volgende uitvoer. Dit betekent dat uw app actief is en klaar is voor het ontvangen van aanvragen.

Now listening on: http://localhost:6000

Als u het programma wilt stoppen, selecteert u Ctrl+C in de opdrachtshell. U kunt de app opnieuw uitvoeren met behulp van de node app.js-opdracht.

Tip

U kunt ook het foutopsporingsprogramma van Visual Studio Code gebruiken om de dotnet run-opdracht uit te voeren. Met het ingebouwde foutopsporingsprogramma van Visual Studio Code kunt u de lus voor bewerken, compileren en fouten opsporen versnellen.

Open een browser en ga naar http://localhost:6000/public. In het browservenster ziet u de volgende tekst, samen met de huidige datum en tijd.

Node.js

Start de web-app in de opdrachtshell door de volgende opdracht uit te voeren:

node app.js

U ziet nu de volgende uitvoer. Dit betekent dat uw app actief is en klaar is voor het ontvangen van aanvragen.

Example app listening on port 6000!

Als u het programma wilt stoppen, selecteert u Ctrl+C in de opdrachtshell. U kunt de app opnieuw uitvoeren met behulp van de node app.js-opdracht.

Tip

U kunt ook het foutopsporingsprogramma van Visual Studio Code gebruiken om de node app.js-opdracht uit te voeren. Met het ingebouwde foutopsporingsprogramma van Visual Studio Code kunt u de lus voor bewerken, compileren en fouten opsporen versnellen.

Open een browser en ga naar http://localhost:6000/public. In het browservenster ziet u de volgende tekst, samen met de huidige datum en tijd.

Stap 8: De web-API aanroepen vanuit uw app

Roep het beveiligde web-API-eindpunt aan zonder toegangstoken. Open een browser en ga naar http://localhost:6000/hello. De API retourneert een foutbericht over niet-geautoriseerde HTTP, wat bevestigt dat de web-API is beveiligd met een Bearer-token.

Ga door met het configureren van uw app om de web-API aan te roepen. Zie de sectie Vereisten voor hulp.

Bekijk deze video voor meer informatie over enkele aanbevolen procedures wanneer u Azure AD B2C integreert met een API.

Volgende stappen

Ga voor het volledige voorbeeld naar GitHub:

ASP.NET Core

• Haal de web-API op met behulp van de Microsoft-identiteitsbibliotheek.

Node.js

• Haal de web-API op met behulp van de Passport.js-bibliotheek.