Teilen über

Szenario: Aufrufen einer Web-API durch eine Web-API (On-Behalf-Of-Szenario)

Erfahren Sie, wie Sie eine Web-API erstellen, die im Auftrag des Benutzers eine andere Web-API aufruft.

Bevor Sie diesen Artikel lesen, sollten Sie mit den AD FS-Konzepten und dem On-Behalf_Of-Fluss vertraut sein.

Übersicht

  • Ein Client bzw. eine Web-App (in der Abbildung unten nicht dargestellt) ruft eine geschützte Web-API auf und stellt ein JWT-Bearertoken im zugehörigen HTTP-Autorisierungsheader zur Verfügung.

  • Die geschützte Web-API überprüft das Token und verwendet die MSAL-Methode AcquireTokenOnBehalfOf, um (von AD FS) ein weiteres Token anzufordern, damit sie im Auftrag des Benutzers eine zweite Web-API (die sogenannte Downstream-Web-API) aufrufen kann.

  • Die geschützte Web-API verwendet dieses Token, um eine Downstream-API aufzurufen. Sie kann außerdem „AcquireTokenSilentlater“ aufrufen, um Token für weitere Downstream-APIs anzufordern (aber weiterhin im Auftrag desselben Benutzers). Mit „AcquireTokenSilent“ wird das Token bei Bedarf aktualisiert.

    Übersicht

Um besser nachvollziehen zu können, wie Sie das Authentifizierungsszenario in AD FS konfigurieren, verwenden wir das hier verfügbare Beispiel und gehen die Schritte zur App-Registrierung und Codekonfiguration durch.

Voraussetzungen

  • GitHub-Clienttools
  • AD FS 2019 oder höher ist konfiguriert und wird ausgeführt
  • Visual Studio 2013 oder höher

App-Registrierung in AD FS

Dieser Abschnitt zeigt, wie Sie die native App als öffentlichen Client und Web-APIs als vertrauende Seite in AD FS registrieren.

  1. Klicken Sie in „AD FS-Verwaltung“ mit der rechten Maustaste auf Anwendungsgruppen, und wählen Sie Anwendungsgruppe hinzufügen aus.

  2. Geben Sie im Assistenten zum Erstellen von Anwendungsgruppen als Name den Wert WebApiToWebApi ein, und wählen Sie unter Client/Server-Anwendungen die Vorlage Systemeigene Anwendung mit Zugriff auf eine Web-API zugreift. Klicken Sie auf Weiter.

    Screenshot: Willkommensseite des Assistenten zum Hinzufügen von Anwendungsgruppen mit hervorgehobener Vorlage „Systemeigene Anwendung mit Zugriff auf eine Web-API“

  3. Kopieren Sie den Wert für den Clientbezeichner. Dieser wird später als Wert für ClientId in der Datei App.config der Anwendung verwendet. Geben Sie den folgenden Umleitungs-URI ein: https://ToDoListClient. Klicken Sie auf Hinzufügen. Klicken Sie auf Weiter.

    Screenshot: Seite „Native Anwendung“ im Assistenten zum Hinzufügen von Anwendungsgruppen mit Anzeige des Umleitungs-U R I

  4. Geben Sie auf dem Bildschirm „Web-API konfigurieren“ den folgenden Bezeichner ein: https://localhost:44321/. Klicken Sie auf Hinzufügen. Klicken Sie auf Weiter. Dieser Wert wird später in den Dateien App.config und Web.Config der Anwendung verwendet.

    Screenshot: Seite „Web-API konfigurieren“ im Assistenten zum Hinzufügen von Anwendungsgruppen mit Anzeige des korrekten Bezeichners

  5. Wählen Sie auf dem Bildschirm „Zugriffssteuerungsrichtlinie anwenden“ die Option Jedem Einzelnen Zugriff gewähren aus, und klicken Sie auf Weiter.

    Screenshot: Seite „Zugriffssteuerungsrichtlinie auswählen“ im Assistenten zum Hinzufügen von Anwendungsgruppen mit hervorgehobener Option „Jedem Einzelnen Zugriff gewähren“

  6. Wählen Sie auf dem Bildschirm „Anwendungsberechtigungen konfigurieren“ die Optionen openid und user_impersonation aus. Klicken Sie auf Weiter.

    Screenshot: Seite „Anwendungsberechtigungen konfigurieren“ im Assistenten zum Hinzufügen von Anwendungsgruppen mit ausgewählter Option „openid“

  7. Klicken Sie auf dem Bildschirm „Zusammenfassung“ auf Weiter.

  8. Klicken Sie auf dem Bildschirm „Abschließen“ auf Schließen.

  9. Klicken Sie in „AD FS-Verwaltung“ auf Anwendungsgruppen, und wählen Sie die Anwendungsgruppe WebApiToWebApi aus. Klicken Sie mit der rechten Maustaste, und wählen Sie Eigenschaften aus.

    Screenshot: Dialogfeld „A D F S-Verwaltung“ mit hervorgehobener Gruppe „WebApiToWebApi“ und der Option „Eigenschaften“ in der Dropdownliste

  10. Klicken Sie im Eigenschaftendialogfeld für „WebApiToWebApi“ auf Anwendung hinzufügen....

    Screenshot: Eigenschaftendialogfeld für „WebApiToWebApi“ mit aufgelisteter Anwendung „WebApiToWebApi – Web-A P I“

  11. Wählen Sie unter „Eigenständige Anwendungen“ die Option Serveranwendung aus.

    Screenshot: Willkommensseite des Assistenten zum Hinzufügen einer neuen Anwendung zu „WebApiToWebApi“ mit hervorgehobener Option „Serveranwendung“

  12. Fügen Sie auf dem Bildschirm „Serveranwendung“ https://localhost:44321/ als Clientbezeichner und Umleitungs-URI hinzu.

    Screenshot: Seite „Serveranwendung“ im Assistenten zum Hinzufügen einer neuen Anwendung zu „WebApiToWebApi“ mit Anzeige des korrekten Clientbezeichners und des Umleitungs-U R I

  13. Wählen Sie auf dem Bildschirm „Anwendungsanmeldeinformationen konfigurieren“ die Option Gemeinsamen geheimen Schlüssel generieren aus. Kopieren Sie das Geheimnis zur späteren Verwendung.

    Screenshot: Seite „Anwendungsanmeldeinformationen konfigurieren“ im Assistenten zum Hinzufügen einer neuen Anwendung zu „WebApiToWebApi“ mit ausgewählter Option „Gemeinsamen geheimen Schlüssel generieren“ und hervorgehobenem Geheimnis

  14. Klicken Sie auf dem Bildschirm „Zusammenfassung“ auf Weiter.

  15. Klicken Sie auf dem Bildschirm „Abschließen“ auf Schließen.

  16. Klicken Sie in „AD FS-Verwaltung“ auf Anwendungsgruppen, und wählen Sie die Anwendungsgruppe WebApiToWebApi aus. Klicken Sie mit der rechten Maustaste, und wählen Sie Eigenschaften aus.

    Screenshot 2: Dialogfeld „A D F S-Verwaltung“ mit hervorgehobener Gruppe „WebApiToWebApi“ und der Option „Eigenschaften“ in der Dropdownliste

  17. Klicken Sie im Eigenschaftendialogfeld für „WebApiToWebApi“ auf Anwendung hinzufügen....

    Screenshot 2: Eigenschaftendialogfeld für „WebApiToWebApi“ mit aufgelisteter Anwendung „WebApiToWebApi – Web-A P I“

  18. Wählen Sie unter „Eigenständige Anwendungen“ die Option Web-API aus.

    Screenshot: Willkommensseite des Assistenten zum Hinzufügen einer neuen Anwendung zu „WebApiToWebApi“ mit hervorgehobener Option „Web-A P I“

  19. Fügen Sie unter „Web-API konfigurieren“ https://localhost:44300 als Bezeichner hinzu.

    Screenshot: Seite „Web-A P I konfigurieren“ im Assistenten zum Hinzufügen einer neuen Anwendung zu „WebApiToWebApi“ mit Anzeige des korrekten Umleitungs-U R I

  20. Wählen Sie auf dem Bildschirm „Zugriffssteuerungsrichtlinie anwenden“ die Option Jedem Einzelnen Zugriff gewähren aus, und klicken Sie auf Weiter.

    Screenshot: Seite „Zugriffssteuerungsrichtlinie auswählen“ im Assistenten zum Hinzufügen einer neuen Anwendung zu „WebApiToWebApi“ mit hervorgehobener Option „Jedem Einzelnen Zugriff gewähren“

  21. Klicken Sie auf dem Bildschirm „Anwendungsberechtigungen konfigurieren“ auf Weiter.

    Screenshot: Seite „Anwendungsberechtigungen konfigurieren“ im Assistenten zum Hinzufügen einer neuen Anwendung zu „WebApiToWebApi“ mit hervorgehobener Option „Weiter“

  22. Klicken Sie auf dem Bildschirm „Zusammenfassung“ auf Weiter.

  23. Klicken Sie auf dem Bildschirm „Abschließen“ auf Schließen.

  24. Klicken Sie im Eigenschaftendialogfeld „WebApiToWebApi – Web-API 2“ auf OK.

  25. Wählen Sie im Eigenschaftendialogfeld von „WebApiToWebApi“ WebApiToWebApi – Web-API aus, und klicken Sie auf Bearbeiten.

    Screenshot: Eigenschaftendialogfeld für „WebApiToWebApi“ mit hervorgehobener Anwendung „WebApiToWebApi – Web-A P I“

  26. Wählen Sie im Eigenschaftendialogfeld „WebApiToWebApi – Web-API“ die Registerkarte Ausstellungstransformationsregeln aus, und klicken Sie auf Regel hinzufügen....

    Screenshot: Eigenschaftendialogfeld „WebApiToWebApi – Web-A P I“ mit angezeigter Registerkarte „Ausstellungstransformationsregeln“

  27. Wählen Sie im Assistenten zum Hinzufügen einer Transformationsanspruchsregel die Option Ansprüche mithilfe einer benutzerdefinierten Regel senden aus der Dropdownliste aus, und klicken Sie dann auf Weiter.

    Screenshot: Seite „Regelvorlage auswählen“ im Assistenten zum Hinzufügen einer Transformationsanspruchsregel mit ausgewählter Option „Ansprüche mithilfe einer benutzerdefinierten Regel senden“

  28. Geben Sie im Feld Anspruchsregelname den Wert PassAllClaims und im Feld „Benutzerdefinierte Regel“ die Anspruchsregel x:[] => issue(claim=x); ein. Klicken Sie anschließend auf „Fertig stellen“.

    Screenshot: Seite „Regel konfigurieren“ im Assistenten zum Hinzufügen einer Transformationsanspruchsregel mit der oben beschriebenen Konfiguration

  29. Klicken Sie im Eigenschaftendialogfeld „WebApiToWebApi – Web-API“ auf OK.

  30. Wählen Sie im Eigenschaftendialogfeld von „WebApiToWebApi“ die Option „WebApiToWebApi – Web-API 2“ aus, und klicken Sie auf „Bearbeiten“.
    Screenshot: Eigenschaftendialogfeld von „WebApiToWebApi“ mit hervorgehobener Anwendung „WebApiToWebApi – Web-A P I 2“

  31. Wählen Sie im Eigenschaftendialogfeld „WebApiToWebApi – Web-API 2“ die Registerkarte „Ausstellungstransformationsregeln“ aus, und klicken Sie auf „Regel hinzufügen“.

  32. Wählen Sie im Assistenten zum Hinzufügen einer Transformationsanspruchsregel in der Dropdownliste die Option „Ansprüche mithilfe einer benutzerdefinierten Regel senden“, und klicken Sie auf „Weiter“.Screenshot 2: Seite „Regelvorlage auswählen“ im Assistenten zum Hinzufügen einer Transformationsanspruchsregel mit ausgewählter Option „Ansprüche mithilfe einer benutzerdefinierten Regel senden“

  33. Geben Sie im Feld „Anspruchsregelname“ den Wert „PassAllClaims“und im Feld Benutzerdefinierte Regel die Anspruchsregel x:[] => issue(claim=x); ein. Klicken Sie anschließend auf Fertig stellen.

    Screenshot 2: Seite „Regel konfigurieren“ im Assistenten zum Hinzufügen einer Transformationsanspruchsregel mit der oben beschriebenen Konfiguration

  34. Klicken Sie im Eigenschaftendialogfeld „WebApiToWebApi – Web-API 2“ auf OK und dann auf das Eigenschaftendialogfeld „WebApiToWebApi“.

Codekonfiguration

In diesem Abschnitt wird gezeigt, wie Sie eine Web-API konfigurieren, um eine andere Web-API aufzurufen.

  1. Laden Sie das Beispiel hier herunter.

  2. Öffnen Sie das Beispiel mit Visual Studio.

  3. Öffnen Sie die Datei App.config. Ändern Sie Folgendes:

    • ida:Authority: Geben Sie https://[your AD FS hostname]/adfs/ ein.

    • ida:ClientId: Geben Sie den Wert aus Schritt 3 im Abschnitt „App-Registrierung in AD FS“ weiter oben ein.

    • ida:RedirectUri: Geben Sie den Wert aus Schritt 3 im Abschnitt „App-Registrierung in AD FS“ weiter oben ein.

    • todo:TodoListResourceId: Geben Sie den Bezeichnerwert aus Schritt 4 im Abschnitt „App-Registrierung in AD FS“ weiter oben ein.

    • ida: todo:TodoListBaseAddress: Geben Sie den Bezeichner-Wert aus Schritt 4 im Abschnitt „App-Registrierung in AD FS“ weiter oben ein.

      Screenshot: Datei „App.config“ mit Anzeige der geänderten Werte

  4. Öffnen Sie die Datei „Web.config“ unter „ToDoListService“. Ändern Sie Folgendes:

    • ida:Audience: Geben Sie die Client-ID aus Schritt 12 im Abschnitt „App-Registrierung in AD FS“ weiter oben ein.

    • ida:ClientId: Geben Sie die Client-ID aus Schritt 12 im Abschnitt „App-Registrierung in AD FS“ weiter oben ein.

    • Ida: ClientSecret: Geben Sie das gemeinsame Geheimnis ein, das Sie aus Schritt 13 im Abschnitt „App-Registrierung in AD FS“ weiter oben kopiert haben.

    • ida:RedirectUri: Geben Sie den RedirectUri-Wert aus Schritt 12 im Abschnitt „App-Registrierung in AD FS“ weiter oben ein.

    • ida: AdfsMetadataEndpoint: Geben Sie https://[Ihr_AD FS_Hostname]/federationmetadata/2007-06/federationmetadata.xml ein.

    • ida:OBOWebAPIBase: Geben Sie den Bezeichnerwert aus Schritt 19 im Abschnitt „App-Registrierung in AD FS“ weiter oben ein.

    • ida:Authority: Geben Sie https://[Ihr_AD FS_Hostname]/adfs ein.

      Screenshot: Datei „Web.config“ unter „ToDoListService“ mit Anzeige der geänderten Werte

  5. Öffnen Sie die Datei „Web.config“ unter „WebAPIOBO“. Ändern Sie Folgendes:

    • ida: AdfsMetadataEndpoint: Geben Sie https://[Ihr_AD FS_Hostname]/federationmetadata/2007-06/federationmetadata.xml ein.

    • ida:Audience: Geben Sie die Client-ID aus Schritt 12 im Abschnitt „App-Registrierung in AD FS“ weiter oben ein.

      Screenshot: Datei „Web.config“ unter „WebAPIOBO“ mit Anzeige der geänderten Werte

Testen des Beispiels

In diesem Abschnitt wird gezeigt, wie Sie das oben konfigurierte Beispiel testen.

Nachdem die Codeänderungen vorgenommen wurden, erstellen Sie die Projektmappe neu.

  1. Klicken Sie in Visual Studio mit der rechten Maustaste auf die Projektmappe, und wählen Sie Startprojekte festlegen... aus.

    Screenshot: Angezeigte Liste bei einem Rechtsklick auf die Projektmappe mit hervorgehobener Option „Startprojekte festlegen“

  2. Vergewissern Sie sich auf den Eigenschaftsseiten, dass Aktion für alle Projekte mit Ausnahme von „TodoListSPA“ auf Start festgelegt ist.

    Screenshot: Eigenschaftenseite des Startprojekts mit ausgewählter Option „Mehrere Startprojekte“ und festgelegter Aktion „Start“ für alle Projekte

  3. Klicken Sie oben in Visual Studio auf den grünen Pfeil.

    Screenshot: Visual Studio-Benutzeroberfläche mit hervorgehobener Option „Start“

  4. Klicken Sie auf dem Hauptbildschirm der nativen App auf Anmelden.

    Screenshot: Dialogfeld mit dem To Do List-Client

    Wenn der Bildschirm der nativen App nicht angezeigt wird, suchen Sie in dem Ordner auf Ihrem System, in dem das Projektrepository gespeichert ist, nach den Dateien „*msalcache.bin“, und entfernen Sie sie.

  5. Sie werden an die AD FS-Anmeldeseite umgeleitet. Melden Sie sich bei Azure an.

    Screenshot: Seite für die Anmeldung

  6. Geben Sie nach der Anmeldung im Abschnitt Aufgabe erstellen den Text „Aufruf von Web-API zu Web-API“ ein. Klicken Sie auf Element hinzufügen. Dadurch wird die Web-API (To Do List-Dienst) aufgerufen, die dann die Web-API 2 (WebAPIOBO) aufruft und das Element in den Cache einfügt.

    Screenshot: Dialogfeld „To Do List-Client“ mit dem neuen To Do-Element zum Auffüllen des Abschnitts „To Do-Elemente“

Nächste Schritte

AD FS OpenID Connect-/OAuth-Flows und Anwendungsszenarien