Aktivieren der Authentifizierung in Ihrer eigenen Web-API mit Azure AD B2C

Wenn Sie den Zugriff auf eine Web-API autorisieren möchten, können Sie nur Anforderungen bereitstellen, die ein gültiges Zugriffstoken enthalten, das Azure Active Directory B2C (Azure AD B2C) ausstellt. In diesem Artikel erfahren Sie, wie Sie Azure AD B2C-Autorisierung für Ihre Web-API aktivieren. Nachdem Sie die Schritte in diesem Artikel ausgeführt haben, sind nur Benutzer, die ein gültiges Zugriffstoken erhalten, berechtigt, Ihre Web-API-Endpunkte aufzurufen.

Voraussetzungen

Lesen Sie zunächst einen der folgenden Artikel, in denen erläutert wird, wie Sie die Authentifizierung für Apps konfigurieren, die Web-APIs aufrufen. Führen Sie dann die Schritte in diesem Artikel aus, um die Beispiel-Web-API durch Ihre eigene Web-API zu ersetzen.

• Konfigurieren der Authentifizierung in einer Beispielwebanwendung, die eine Web-API mithilfe von Azure Active Directory B2C aufruft
• Konfigurieren der Authentifizierung in einem Beispiel einer Single-Page-Webanwendung (SPA) mithilfe von Azure AD B2C

Überblick

Die tokenbasierte Authentifizierung stellt sicher, dass Anforderungen an eine Web-API ein gültiges Zugriffstoken enthalten.

Die App führt die folgenden Schritte aus:

1. Sie authentifiziert Benutzer mit Azure AD B2C.

2. Sie erwirbt ein Zugriffstoken mit den erforderlichen Berechtigungen (Bereichen) für den Web-API-Endpunkt.

3. Sie übergibt das Zugriffstoken als Bearertoken im Autorisierungsheader der HTTP-Anforderung in folgendem Format:

   Authorization: Bearer <access token>
   

Die Web-API führt die folgenden Schritte aus:

1. Sie liest das Bearertoken aus dem Autorisierungsheader in der HTTP-Anforderung.

2. Sie überprüft das Token.

3. Sie überprüft die Berechtigungen (Bereiche) im Token.

4. Sie liest die Ansprüche, die im Token codiert sind (optional).

5. Sie antwortet auf die HTTP-Anforderung.

Übersicht über die App-Registrierung

Damit sich Ihre App mit Azure AD B2C anmelden und eine Web-API aufrufen kann, müssen Sie im Azure AD B2C-Verzeichnis zwei Anwendungen registrieren.

• Durch die Web-, mobile oder SPA-Anwendungsregistrierung kann sich Ihre App bei Azure AD B2C anmelden. Beim App-Registrierungsprozess wird eine Anwendungs-ID generiert, die auch als Client-ID bezeichnet wird und Ihre Anwendung eindeutig identifiziert (Beispiel: App ID: 1).

• Durch die Web-API-Registrierung kann Ihre App eine geschützte Web-API aufrufen. Die Registrierung macht die Web-API-Berechtigungen (Bereiche) verfügbar. Beim App-Registrierungsprozess wird eine Anwendungs-ID generiert, die Ihre Web-API eindeutig identifiziert (Beispiel: App ID: 2). Erteilen Sie Ihrer App (App-ID: 1) Berechtigungen für die Web-API-Bereiche (App-ID: 2).

Die Anwendungsregistrierungen und die Anwendungsarchitektur werden im folgenden Diagramm beschrieben:

Vorbereiten Ihrer Entwicklungsumgebung

In den nächsten Abschnitten erstellen Sie ein neues Web-API-Projekt. Wählen Sie Ihre Programmiersprache aus, ASP.NET Core oder Node.js. Sie benötigen unbedingt einen Computer, auf dem eine der folgenden Softwares ausgeführt wird:

ASP.NET Core

• Visual Studio Code
• C# für Visual Studio Code (neueste Version)
• .NET 5.0 SDK

Node.js

• Visual Studio Code oder ein anderer Code-Editor
• Node.js-Runtime

Schritt 1: Erstellen einer geschützten Web-API

Erstellen Sie ein neues Web-API-Projekt. Wählen Sie zunächst die Programmiersprache aus, die Sie verwenden möchten, ASP.NET Core oder Node.js.

ASP.NET Core

Verwenden Sie den Befehl dotnet new. Der dotnet new-Befehl erstellt einen neuen Ordner namens TodoList mit den Web-API-Projekt-Ressourcen. Öffnen Sie das Verzeichnis und dann Visual Studio Code.

dotnet new webapi -o TodoList
cd TodoList
code . 

Wenn Sie zum „Hinzufügen der erforderlichen Ressourcen zum Projekt“ aufgefordert werden, wählen Sie Ja aus.

Node.js

Verwenden Sie Express für Node.js, um eine Web-API zu erstellen. Gehen Sie folgendermaßen vor, um eine Web-API zu erstellen:

1. Erstellen Sie einen neuen Ordner mit dem Namen TodoList.
2. Erstellen Sie im Ordner TodoList eine Datei namens app.js.
3. Führen Sie in einer Befehlsshell npm init -y aus. Dieser Befehl erstellt eine Standarddatei namens package.json für Ihr Node.js-Projekt.
4. Führen Sie npm install express in der Befehlsshell aus. Dieser Befehl installiert das Express-Framework.

Schritt 2: Installieren der Abhängigkeiten

Fügen Sie ihrem Web-API-Projekt die Authentifizierungsbibliothek hinzu. Die Authentifizierungsbibliothek analysiert den HTTP-Authentifizierungsheader, überprüft das Token und extrahiert Ansprüche. Weitere Informationen finden Sie in der Dokumentation zur Bibliothek.

ASP.NET Core

Um die Authentifizierungsbibliothek hinzuzufügen, installieren Sie das Paket, indem Sie den folgenden Befehl ausführen:

dotnet add package Microsoft.Identity.Web

Node.js

Um die Authentifizierungsbibliothek hinzuzufügen, installieren Sie das Paket, indem Sie den folgenden Befehl ausführen:

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

Das morgan-Paket ist eine Middleware für die HTTP-Anforderungsprotokollierung für Node.js.

Schritt 3: Initiieren der Authentifizierungsbibliothek

Fügen Sie den zum Initiieren der Authentifizierungsbibliothek erforderlichen Code hinzu.

ASP.NET Core

Öffnen Sie Startup.cs, und fügen Sie am Anfang der Klasse die folgenden using-Deklarationen hinzu:

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

Suchen Sie die Funktion ConfigureServices(IServiceCollection services). Fügen Sie dann vor der services.AddControllers();-Codezeile den folgenden Codeausschnitt hinzu:

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

Suchen Sie die Funktion Configure. Fügen Sie dann unmittelbar nach der app.UseRouting();-Codezeile den folgenden Codeausschnitt hinzu:

app.UseAuthentication();

Nach den Änderungen sollte Ihr Code wie der folgende Codeausschnitt aussehen:

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

Fügen Sie Ihrer app.js-Datei den folgenden JavaScript-Code hinzu.

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

Schritt 4: Hinzufügen der Endpunkte

Fügen Sie Ihrer Web-API zwei Endpunkte hinzu:

• Anonymer /public-Endpunkt. Dieser Endpunkt gibt das aktuelle Datum und die aktuelle Uhrzeit zurück. Verwenden Sie ihn, um Ihre Web-API mit anonymen Aufrufen zu debuggen.
• Geschützter /hello-Endpunkt. Dieser Endpunkt gibt den Wert des name-Anspruchs innerhalb des Zugriffstokens zurück.

So fügen Sie den anonymen Endpunkt hinzu:

ASP.NET Core

Fügen Sie im Ordner /Controllers eine PublicController.cs-Datei hinzu, und fügen Sie sie dann dem folgenden Codeausschnitt hinzu:

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

Fügen Sie in der app.js-Datei den folgenden JavaScript-Code hinzu:

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

So fügen Sie den geschützten Endpunkt hinzu:

ASP.NET Core

Fügen Sie im Ordner /Controllers eine HelloController.cs-Datei hinzu, und fügen Sie sie dann dem folgenden Code hinzu:

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

Der HelloController-Controller ist mit dem AuthorizeAttribute versehen, das den Zugriff auf authentifizierte Benutzer beschränkt.

Der Controller ist auch mit dem [RequiredScope("tasks.read")] versehen. Das RequiredScopeAttribute überprüft, ob die Web-API mit den richtigen Bereichen aufgerufen wird, tasks.read.

Node.js

Fügen Sie in der app.js-Datei den folgenden JavaScript-Code hinzu:

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

Der /hello-Endpunkt ruft zunächst die passport.authenticate()-Funktion auf. Die Authentifizierungsfunktion schränkt den Zugriff auf authentifizierte Benutzer ein.

Die Authentifizierungsfunktion überprüft auch, ob die Web-API mit den richtigen Bereichen aufgerufen wird. Die zulässigen Bereiche werden in der Konfigurationsdatei aufgeführt.

Schritt 5: Konfigurieren des Web-Servers

Legen Sie in einer Entwicklungsumgebung fest, dass die Web-API an der Portnummer für eingehende HTTP- oder HTTPS-Anforderungen lauscht. Verwenden Sie in diesem Beispiel HTTP-Port 6000 und HTTPS-Port 6001. Der Basis-URI der Web-API ist http://localhost:6000 für HTTP und https://localhost:6001 für HTTPS.

ASP.NET Core

Fügen Sie der Datei appsettings.json den folgenden JSON-Ausschnitt hinzu.

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

Node.js

Fügen Sie der app.js-Datei den folgenden JavaScript-Code hinzu. Es ist möglich, HTTP- und HTTPS-Endpunkte für die Node-Anwendung einzurichten.

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

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

Schritt 6: Konfigurieren der Web-API

Fügen Sie einer Konfigurationsdatei Konfigurationen hinzu. Die Datei enthält Informationen zu Ihrem Azure AD B2C-Identitätsanbieter. Die Web-API-App überprüft anhand dieser Informationen das Zugriffstoken, das die Web-App als Bearertoken übergibt.

ASP.NET Core

Öffnen Sie im Projektstammordner die Datei appsettings.json, und fügen Sie folgende Einstellungen hinzu:

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

Aktualisieren Sie in der Datei appsettings.json die folgenden Eigenschaften:

`Section`	Key	Wert
AzureAdB2C	Instanz	Der erste Teil Ihres Azure AD B2C-Mandantennamens (z. B. https://contoso.b2clogin.com).
AzureAdB2C	Domain	Der vollständige Name Ihres Azure AD B2C-Mandanten (z. B. contoso.onmicrosoft.com).
AzureAdB2C	ClientId	Die ID der Web-API-Anwendung. Im obigen Diagramm ist dies die Anwendung mit der App-ID: 2. Informationen zum Abrufen der Registrierungs-ID Ihrer Web-API-Anwendung finden Sie unter Voraussetzungen.
AzureAdB2C	SignUpSignInPolicyId	Die Benutzerflows oder die benutzerdefinierte Richtlinie. Informationen zum Abrufen Ihres Benutzerflows oder Ihrer Richtlinie finden Sie unter Voraussetzungen.

Node.js

Erstellen Sie im Stammordner des Projekts eine config.json-Datei, und fügen Sie sie dann dem folgenden JSON-Ausschnitt hinzu:

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

Aktualisieren Sie in der config.json-Datei folgende Eigenschaften:

`Section`	Key	Wert
Anmeldeinformationen	tenantName	Der Name Ihres Azure AD B2C-Mandantenname/Domänenname (z. B. contoso.onmicrosoft.com).
Anmeldeinformationen	clientID	Die ID der Web-API-Anwendung. Im obigen Diagramm ist dies die Anwendung mit der App-ID: 2. Informationen zum Abrufen der Registrierungs-ID Ihrer Web-API-Anwendung finden Sie unter Voraussetzungen.
Anmeldeinformationen	Issuer (Aussteller)	Der Anspruchswert des Tokenausstellers iss. Azure AD B2C gibt das Token standardmäßig im folgenden Format zurück: https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/. Ersetzen Sie <your-tenant-name> durch den ersten Teil des Namens Ihres Azure AD B2C-Mandanten. Ersetzen Sie <your-tenant-ID> durch die ID Ihres Azure AD B2C-Mandanten.
Richtlinien	policyName	Die Benutzerflows oder die benutzerdefinierte Richtlinie. Informationen zum Abrufen Ihres Benutzerflows oder Ihrer Richtlinie finden Sie unter Voraussetzungen.
resource	scope	Die Bereiche ihrer Web-API-Anwendungsregistrierung. Wie Sie Ihren Web-API-Bereich abrufen, erfahren Sie unter Voraussetzungen.

Schritt 7: Ausführen und Testen der Web-API

Führen Sie abschließend die Web-API mit Ihren Azure AD B2C-Umgebungseinstellungen aus.

ASP.NET Core

Starten Sie die Web-App in der Befehlsshell mit folgendem Befehl:

 dotnet run

Die folgende Ausgabe sollte angezeigt werden. Dies bedeutet, dass Ihre App ausgeführt wird und zum Empfang von Anforderungen bereit ist.

Now listening on: http://localhost:6000

Um das Programm zu beenden, wählen Sie in der Befehlsshell STRG+C aus. Sie können die App mit dem Befehl node app.js erneut ausführen.

Tipp

Alternativ können Sie den Befehl dotnet run auch mit dem Visual Studio Code-Debugger ausführen. Mit dem integrierten Debugger von Visual Studio Code können Sie Ihre Bearbeitungs-, Kompilierungs- und Debugschleife beschleunigen.

Öffnen Sie einen Browser, und wechseln Sie zu http://localhost:6000/public. Im Browserfenster sollte der folgende Text zusammen mit dem aktuellen Datum und der aktuellen Uhrzeit angezeigt werden.

Node.js

Starten Sie die Web-App in der Befehlsshell mit folgendem Befehl:

node app.js

Die folgende Ausgabe sollte angezeigt werden. Dies bedeutet, dass Ihre App ausgeführt wird und zum Empfang von Anforderungen bereit ist.

Example app listening on port 6000!

Um das Programm zu beenden, wählen Sie in der Befehlsshell STRG+C aus. Sie können die App mit dem Befehl node app.js erneut ausführen.

Tipp

Alternativ können Sie den Befehl node app.js auch mit dem Visual Studio Code-Debugger ausführen. Mit dem integrierten Debugger von Visual Studio Code können Sie Ihre Bearbeitungs-, Kompilierungs- und Debugschleife beschleunigen.

Öffnen Sie einen Browser, und wechseln Sie zu http://localhost:6000/public. Im Browserfenster sollte der folgende Text zusammen mit dem aktuellen Datum und der aktuellen Uhrzeit angezeigt werden.

Schritt 8: Aufrufen der Web-API aus Ihrer App

Versuchen Sie, den geschützten Web-API-Endpunkt ohne Zugriffstoken aufzurufen. Öffnen Sie einen Browser, und wechseln Sie zu http://localhost:6000/hello. Die API gibt eine nicht autorisierte HTTP-Fehlermeldung zurück, die bestätigt, dass die Web-API mit einem Bearertoken geschützt ist.

Fahren Sie mit dem Konfigurieren Ihrer App zum Aufrufen der Web-API fort. Weitere Informationen finden Sie im Abschnitt Voraussetzungen.

Sehen Sie sich dieses Video an, um einige bewährte Verfahren für die Integration von Azure AD B2C mit einer API kennenzulernen.

Nächste Schritte

Rufen Sie das vollständige Beispiel auf GitHub ab:

ASP.NET Core

• Rufen Sie die Web-API mit der Microsoft-Identitätsbibliothek ab.

Node.js

• Rufen Sie die Web-API mit der Passport.js-Bibliothek ab.