Freigeben über

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

  • Artikel

Gilt für: Windows Server 2022, Windows Server 2019, AD FS 2019 und höher

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.

    overview

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 of the Welcome page of the Add Application Group Wizard showing the Native application accessing a Web API template highlighted.

  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 of the Native application page of the Add Application Group Wizard showing the redirect 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 of the Configure Web API page of the Add Application Group Wizard showing the correct identifier.

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

    Screenshot of the Choose Access Control Policy page of the Add Application Group Wizard showing the Permit everyone option highlighted.

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

    Screenshot of the Configure Application Permissions page of the Add Application Group Wizard showing open I D selected.

  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 Eigenschaftenaus.

    Screenshot of the A D F S Management dialog box showing the WebApiToWebApi group highlighted and the Properties option in the dropdown list.

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

    Screenshot of the WebApiToWebApi Properties dialog box showing the WebApiToWebApi - Web A P I application listed.

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

    Screenshot of the Welcome page of the Add a new application to WebApiToWebApi wizard showing the Server application option highlighted.

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

    Screenshot of the Server application page of the Add a new application to WebApiToWebApi wizard showing the correct client identifier and redirect 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 of the Configure Application Credentials application page of the Add a new application to WebApiToWebApi wizard showing the Generate a shared secret option selected and the generated shared secret highlighted.

  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 Eigenschaftenaus.

    Second screenshot of the A D F S Management dialog box showing the WebApiToWebApi group highlighted and the Properties option in the dropdown list.

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

    Second screenshot of the WebApiToWebApi Properties dialog box showing the WebApiToWebApi - Web A P I application listed.

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

    Screenshot of the Welcome page of the Add a new application to WebApiToWebApi wizard showing the Web A P I option highlighted.

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

    Screenshot of the Configure Web A P I page of the Add a new application to WebApiToWebApi wizard showing the correct redirect 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 of the Choose Access Control Policy page of the Add a new application to WebApiToWebApi wizard showing the Permit everyone option highlighted.

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

    Screenshot of the Configure Application Permissions page of the Add a new application to WebApiToWebApi wizard showing the Next option called out.

  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 of the WebApiToWebApi Properties dialog box showing the WebApiToWebApi - Web A P I application highlighted.

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

    Screenshot of the WebApiToWebApi - Web A P I Properties dialog box showing the Issuance Transform Rules tab.

  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 of the Select Rule Template page of the Add Transform Claim Rule Wizard showing the Send Claims Using a Custom Rule option selected.

  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 of the Configure Rule page of the Add Transform Claim Rule Wizard showing the configuration explained above.

  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 of the WebApiToWebApi Properties dialog box showing the WebApiToWebApi - Web A P I 2 application highlighted.

  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“.Second screenshot of the Select Rule Template page of the Add Transform Claim Rule Wizard showing the Send Claims Using a Custom Rule option selected.

  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.

    Second screenshot of the Configure Rule page of the Add Transform Claim Rule Wizard showing the configuration explained above.

  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 Bezeichnerwert aus Schritt 4 im Abschnitt „App-Registrierung in AD FS“ weiter oben ein.

      Screenshot of the App config file showing the modified values.

  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 of the web config file under ToDoListService showing the modified values.

  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 of the web config file under WebAPIOBO showing the modified values.

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 of the list that appears when you right-click the solution with the Set Start Up Projects option highlighted.

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

    Screenshot of the Solution Property Pages dialog box showing the Multiple startup project option selected and all of the projects' actions set to Start.

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

    Screenshot of the Visual Studio UI with the Start option called out.

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

    Screenshot of the To Do List Client dialog box.

    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 an.

    Screenshot of the Sign In page.

  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 of the To Do List Client dialog box with the new to do item populating the To Do Items section.

Nächste Schritte

AD FS OpenID Connect-/OAuth-Flows und Anwendungsszenarien