Teilen über

Schnellstart : Anmelden von Benutzern und Aufrufen einer Web-API im Beispiel Node.js Web-App

Gilt für: Grüner Kreis mit einem weißen Häkchensymbol, das angibt, dass der folgende Inhalt für externe Mandanten gilt. Externe Mandanten (weitere Informationen)

In dieser Schnellstartanleitung erfahren Sie, wie Sie Benutzer anmelden und eine Web-API aus einer Node.js Webanwendung in Ihrem externen Mandanten aufrufen. Die Beispielanwendung ruft eine .NET-API auf. Die Beispielwebanwendung verwendet die Microsoft Authentication Library (MSAL) für Node, um die Authentifizierung zu verarbeiten.

Voraussetzungen

Konfigurieren von API-Bereichen und -Rollen

Durch die Registrierung der Web-API müssen Sie API-Bereiche konfigurieren, um die Berechtigungen zu definieren, die eine Clientanwendung für den Zugriff auf die Web-API anfordern kann. Darüber hinaus müssen Sie App-Rollen einrichten, um die für Benutzer oder Anwendungen verfügbaren Rollen anzugeben und der Web-App die erforderlichen API-Berechtigungen zu erteilen, damit sie die Web-API aufrufen kann.

Konfigurieren von API-Bereichen

Eine API muss mindestens einen Bereich (auch Delegierte Berechtigung genannt) veröffentlichen, damit die Clientanwendungen erfolgreich ein Zugriffstoken für einen Benutzer abrufen können. Führen Sie diese Schritte aus, um einen Bereich zu veröffentlichen:

  1. Wählen Sie auf der Seite App-Registrierungen die von Ihnen erstellte API-Anwendung (ciam-ToDoList-api) aus, um ihre Seite Übersicht zu öffnen.

  2. Wählen Sie unter Verwalten die Option Eine API verfügbar machen aus.

  3. Wählen Sie oben auf der Seite neben Anwendungs-ID-URI den Link Hinzufügen aus, um einen für diese Anwendung eindeutigen URI zu generieren.

  4. Akzeptieren Sie den vorgeschlagenen Anwendungs-ID-URI, z. B. api://{clientId}, und wählen Sie Speichern aus. Wenn Ihre Webanwendung ein Zugriffstoken für die Web-API anfordert, fügt sie diesen URI als Präfix für jeden Bereich hinzu, den Sie für die API definieren.

  5. Wählen Sie unter Durch diese API definierte Bereiche die Option Bereich hinzufügen aus.

  6. Geben Sie die folgenden Werte ein, die Lesezugriff auf die API definieren, und wählen Sie dann Bereich hinzufügen aus, um Ihre Änderungen zu speichern:

    Eigentum Wert
    Bereichsname ToDoListe.Lesen
    Wer kann zustimmen? Nur Administratoren
    Anzeigename der Administratoreinwilligung ToDo-Liste des Benutzers/der Benutzerin mit „ToDoListApi“ lesen
    Beschreibung der Zustimmung des Administrators Geben Sie der App Lesezugriff auf die ToDo-Liste des Benutzers/der Benutzerin mithilfe von „ToDoListApi“.
    Staat Aktiviert

  7. Wählen Sie erneut Bereich hinzufügen aus, und geben Sie die folgenden Werte ein, die einen Bereich für Lese- und Schreibzugriff auf die API definieren. Klicken Sie auf Bereich hinzufügen, um Ihre Änderungen zu speichern:

    Eigentum Wert
    Bereichsname ToDoList.ReadWrite
    Wer kann zustimmen? Nur Administratoren
    Anzeigename der Administratoreinwilligung ToDo-Liste des Benutzers mit der „ToDoListApi“ lesen und schreiben
    Beschreibung der Zustimmung des Administrators Erlauben Sie der App das Lesen und Schreiben der ToDo-Liste des Benutzers mit Hilfe der „ToDoListApi“.
    Staat Aktiviert

Erfahren Sie mehr über das Prinzip der geringsten Rechte beim Veröffentlichen von Berechtigungen für eine Web-API.

Konfigurieren von App-Rollen

Eine API muss mindestens eine App-Rolle oder Anwendungsberechtigung veröffentlichen, damit die Client-Apps ein Zugriffstoken für sich selbst erhalten können. Anwendungsberechtigungen sind der Typ von Berechtigungen, die APIs veröffentlichen sollten, wenn sie Clientanwendungen eine erfolgreiche Authentifizierung als sie selbst ermöglichen wollen und keine Benutzerinnen bzw. Benutzer anmelden müssen. Befolgen Sie die folgenden Schritte, um eine Anwendungsberechtigung zu veröffentlichen:

  1. Wählen Sie auf der Seite App-Registrierungen die von Ihnen erstellte Anwendung (z. B. ciam-ToDoList-api) aus, um ihre Seite Übersicht zu öffnen.

  2. Wählen Sie unter Verwalten die Option Anwendungsrollen aus.

  3. Wählen Sie App-Rolle erstellen aus, und geben Sie die folgenden Werte ein. Wählen Sie dann Anwenden aus, um Ihre Änderungen zu speichern:

    Eigentum Wert
    Anzeigename ToDoListe.Lesen.Alle
    Zulässige Mitgliedstypen Anwendungen
    Wert ToDoListe.Lesen.Alle
    BESCHREIBUNG Geben Sie der App Lesezugriff auf die ToDo-Liste aller Benutzer*innen mithilfe von „ToDoListApi“.
    Möchten Sie diese App-Rolle aktivieren? Aktiviert lassen

  4. Wählen Sie erneut App-Rolle erstellen aus, und geben Sie die folgenden Werte für die zweite App-Rolle ein. Wählen Sie dann Anwenden aus, um Ihre Änderungen zu speichern:

    Eigentum Wert
    Anzeigename ToDoList.ReadWrite.All
    Zulässige Mitgliedstypen Anwendungen
    Wert ToDoList.ReadWrite.All
    BESCHREIBUNG Geben Sie der App Lese- und Schreibzugriff auf die ToDo-Liste eines jeden Benutzers mit Hilfe der „ToDoListApi“.
    Möchten Sie diese App-Rolle aktivieren? Aktiviert lassen

Konfigurieren optionaler Ansprüche

Sie können den optionalen idtyp-Anspruch hinzufügen, um der Web-API dabei zu helfen, zu bestimmen, ob es sich bei einem Token um ein App-Token oder ein App- + Benutzertoken handelt. Obwohl Sie eine Kombination aus Scp - und Rollenansprüchen für denselben Zweck verwenden können, ist die Verwendung des idtyp-Anspruchs die einfachste Möglichkeit, ein App-Token und ein App + Benutzertoken voneinander zu unterscheiden. Der Wert dieses Anspruchs ist beispielsweise app, wenn das Token ein reines App-Token ist.

Führen Sie die Schritte im Artikel "Konfigurieren optionaler Ansprüche " aus, um dem Zugriffstoken idtyp-Anspruch hinzuzufügen:

  • Wählen Sie für den Tokentyp"Zugriff" aus.
  • Wählen Sie aus der optionalen Anspruchsliste idtyp aus.

Erteilen von API-Berechtigungen für die Web-App

Führen Sie die folgenden Schritte aus, um Ihrer Clientanwendung (ciam-client-app) API-Berechtigungen zuzuweisen:

  1. Wählen Sie auf der Seite App-Registrierungen die von Ihnen erstellte Anwendung (z. B. ciam-client-app) aus, um ihre Seite Übersicht zu öffnen.

  2. Wählen Sie unter Verwalten die Option API-Berechtigungen aus.

  3. Wählen Sie unter Konfigurierte Berechtigungen die Option Berechtigung hinzufügen aus.

  4. Wählen Sie die Registerkarte Von meiner Organisation verwendete APIs aus.

  5. Wählen Sie in der Liste der APIs die API aus, z. B. ciam-ToDoList-api.

  6. Wählen Sie Delegierte Berechtigungen aus.

  7. Wählen Sie in der Berechtigungsliste ToDoList.Read, ToDoList.ReadWrite aus (verwenden Sie bei Bedarf das Suchfeld).

  8. Wählen Sie die Schaltfläche Berechtigungen hinzufügen aus. An diesem Punkt haben Sie die Berechtigungen ordnungsgemäß zugewiesen. Da der Mandant jedoch der Mandant eines Kunden ist, können Consumer-Benutzende selbst diesen Berechtigungen nicht zustimmen. Um dieses Problem zu beheben, müssen Sie als Administrator im Namen aller Benutzer im Mandanten diesen Berechtigungen zustimmen:

    1. Wählen Sie Administratorzustimmung für <Name Ihres Mandanten> erteilen und dann Ja aus.

    2. Wählen Sie Aktualisieren aus, und vergewissern Sie sich, dass für beide Bereiche unter < der Status Erteilt für >Name Ihres Mandanten angezeigt wird.

  9. Wählen Sie in der Liste Konfigurierte Berechtigungen die Berechtigungen ToDoList.Read und ToDoList.ReadWrite nacheinander aus, und kopieren Sie dann den vollständigen URI der Berechtigung zur späteren Verwendung. Der vollständige Berechtigungs-URI ähnelt api://{clientId}/{ToDoList.Read} oder api://{clientId}/{ToDoList.ReadWrite}.

Klonen oder Herunterladen einer Beispielwebanwendung und Web-API

Um die Beispielanwendung zu erhalten, können Sie sie entweder von GitHub klonen oder als .zip Datei herunterladen.

  • Um das Beispiel zu klonen, öffnen Sie eine Eingabeaufforderung, und navigieren Sie zu der Stelle, an der Sie das Projekt erstellen möchten, und geben Sie den folgenden Befehl ein:

    git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git

  • Laden Sie die .zip Dateiherunter. Extrahieren Sie ihn in einen Dateipfad, in dem die Länge des Namens weniger als 260 Zeichen beträgt.

Installieren von Projektabhängigkeiten

  1. Öffnen Sie ein Konsolenfenster, und wechseln Sie in das Verzeichnis, das die Node.js/Express-Beispiel-App enthält:

    cd 2-Authorization\4-call-api-express\App

  2. Führen Sie die folgenden Befehle aus, um Web-App-Abhängigkeiten zu installieren:

    npm install && npm update

Konfigurieren der Beispiel-Web-App und -API

So verwenden Sie Ihre App-Registrierung im Client-Web-App-Beispiel:

  1. Öffnen Sie die App\authConfig.js-Datei in Ihrem Code-Editor.

  2. Suchen Sie den Platzhalter:

    • Enter_the_Application_Id_Here, und ersetzen Sie ihn durch die Anwendungs-ID (Client) der zuvor von Ihnen registrierten Anwendung. Die Client-App ist eine, die Sie in den Voraussetzungen registriert haben.
    • Enter_the_Tenant_Subdomain_Here und ersetzen Sie es durch die Verzeichnis-(Mandanten-)Unterdomäne. Wenn Ihre primäre Mandantendomäne z. B. contoso.onmicrosoft.comist, verwenden Sie contoso. Wenn Sie Ihren Mandantennamen nicht kennen, lesen Sie die Informationen unter Abrufen der Details des Mandanten.
    • Enter_the_Client_Secret_Here und ersetzen Sie ihn durch den Wert des App-Geheimnisses, den Sie zuvor kopiert haben.
    • Enter_the_Web_Api_Application_Id_Here und ersetzen Sie sie durch die Anwendungs-ID (Client-ID) der Web-API, die Sie zuvor als Teil der Voraussetzungen kopiert haben.

So verwenden Sie Ihre App-Registrierung im Web-API-Beispiel:

  1. Öffnen Sie die API\ToDoListAPI\appsettings.json-Datei in Ihrem Code-Editor.

  2. Suchen Sie den Platzhalter:

    • Enter_the_Application_Id_Here, und ersetzen Sie ihn durch die Anwendungs-ID (Client-ID) der von Ihnen kopierten Web-API. Die Web-API-App ist eine, die Sie zuvor als Teil der Voraussetzungen registriert haben.
    • Enter_the_Tenant_Id_Here, und ersetzen Sie ihn durch die Verzeichnis-ID (Mandanten-ID), die Sie zuvor kopiert haben.
    • Enter_the_Tenant_Subdomain_Here und ersetzen Sie es durch die Verzeichnis-(Mandanten-)Unterdomäne. Wenn Ihre primäre Mandantendomäne z. B. contoso.onmicrosoft.comist, verwenden Sie contoso. Wenn Sie Ihren Mandantennamen nicht kennen, lesen Sie die Informationen unter Abrufen der Details des Mandanten.

Ausführen und Testen der Beispiel-web-App und -API

  1. Öffnen Sie ein Konsolenfenster, und führen Sie dann mit den folgenden Befehlen die Web-API aus:

    cd 2-Authorization\4-call-api-express\API\ToDoListAPI
dotnet run

  2. Führen Sie den Web-App-Client mit den folgenden Befehlen aus:

    cd 2-Authorization\4-call-api-express\App
npm install
npm start

  3. Öffnen Sie Ihren Browser, und navigieren Sie zu http://localhost:3000..

  4. Wählen Sie die Schaltfläche Anmelden aus. Sie werden aufgefordert, sich anzumelden.

    Screenshot der Anmeldung bei einer Node.js-Web-App.

  5. Geben Sie auf der Anmeldeseite Ihre E-Mail-Adresse ein, wählen Sie Weiter aus, geben Sie Ihr Kennwort ein und wählen Sie dann Anmelden aus. Wenn Sie kein Konto besitzen, wählen Sie den Link Kein Konto? Erstellen Sie eins aus, um den Registrierungsflow zu starten.

  6. Wenn Sie die Registrierungsoption auswählen, schließen Sie den gesamten Registrierungsflow ab, nachdem Sie E-Mail-Adresse, Einmal-Passcode, das neue Kennwort und weitere Kontodetails eingegeben haben. Die daraufhin angezeigte Seite sieht in etwa wie im folgenden Screenshot aus. Wenn Sie die Anmeldeoption auswählen, wird eine ähnliche Seite angezeigt.

    Screenshot der Anmeldung bei einer Knoten-Webanwendung und Aufruf einer API.

API aufrufen

  1. Um die API aufzurufen, wählen Sie den Link Todolist anzeigen aus. Die daraufhin angezeigte Seite sieht in etwa wie im folgenden Screenshot aus.

    Screenshot der Bearbeitung der API-Aufgabenliste.

  2. Bearbeiten Sie die Aufgabenliste, indem Sie Elemente erstellen und entfernen.

Funktionsweise

Sie lösen einen API-Aufruf jedes Mal aus, wenn Sie eine Aufgabe anzeigen, hinzufügen oder entfernen. Jedes Mal, wenn Sie einen API-Aufruf auslösen, ruft die Client-Web-App ein Zugriffstoken mit den erforderlichen Berechtigungen (Bereichen) ab, um einen API-Endpunkt aufzurufen. Um beispielsweise eine Aufgabe zu lesen, muss die Client-Web-App ein Zugriffstoken mit ToDoList.Read Berechtigung/Bereich abrufen.

Der Web-API-Endpunkt muss überprüfen, ob die Berechtigungen oder Bereiche im Zugriffstoken, die von der Client-App bereitgestellt werden, gültig sind. Wenn das Zugriffstoken gültig ist, antwortet der Endpunkt auf die HTTP-Anforderung, andernfalls antwortet er mit einem HTTP-Fehler „401 Unauthorized“.

Verwandte Inhalte

  • Last updated on