Geschützte Web-API: App-Registrierung

  • Artikel

Dieser Artikel erläutert die Besonderheiten der App-Registrierung für eine geschützte Web-API.

Die allgemeinen Schritte zum Registrieren einer App sind beschrieben in Schnellstart: Registrieren einer Anwendung bei der Microsoft Identity Platform.

Akzeptierte Tokenversion

Microsoft Identity Platform kann v1.0-Token und v2.0-Token ausgeben. Weitere Informationen zu diesen Token finden Sie unter Zugriffstoken.

Die Tokenversion, die von Ihrer API akzeptiert wird, richtet sich nach den unterstützten Kontotypen, die Sie beim Erstellen der Registrierung Ihrer Web-API-Anwendung im Azure-Portal ausgewählt haben.

  • Wenn der Wert von Unterstützte Kontotypen auf Konten in allen Organisationsverzeichnissen und persönliche Microsoft-Konten (z. B. Skype, Xbox, Outlook.com) festgelegt ist, wird nur Tokenversion v2.0 akzeptiert.
  • Andernfalls wird auch v1.0 als Tokenversion akzeptiert.

Nachdem Sie die Anwendung erstellt haben, können Sie die akzeptierte Tokenversion ermitteln oder ändern, indem Sie die folgenden Schritte ausführen:

  1. Wählen Sie im Azure-Portal Ihre App und dann Manifest aus.
  2. Suchen Sie im Manifest nach der Eigenschaft accessTokenAcceptedVersion.
  3. Der Wert legt für Microsoft Entra fest, welche Token-Version die Web-API akzeptiert.
    • Mit dem Wert „2“ akzeptiert die Web-API v2.0-Token.
    • Ist der Wert Null, akzeptiert die Web-API v1.0-Token.
  4. Falls Sie die Tokenversion geändert haben, wählen Sie Speichern aus.

Die Web-API gibt an, welche Tokenversion akzeptiert wird. Wenn ein Client ein Token für Ihre Web-API von Microsoft Identity Platform anfordert, erhält er ein Token, das angibt, welche Tokenversion die Web-API akzeptiert.

Kein Umleitungs-URI

Web-APIs müssen keinen Umleitungs-URI registrieren, da kein Benutzer interaktiv angemeldet wird.

Verfügbar gemachte API

Weitere für Web-APIs spezifische Einstellungen sind die verfügbar gemachte API und die verfügbar gemachten Bereiche oder App-Rollen.

Bereiche und Anwendungs-ID-URI

Bereiche haben in der Regel das Format resourceURI/scopeName. Bei Microsoft Graph haben die Bereiche Verknüpfungen. User.Read ist beispielsweise eine Verknüpfung für https://graph.microsoft.com/user.read.

Definieren Sie bei der App-Registrierung die folgenden Parameter:

  • Den Ressourcen-URI
  • Mindestens einen Bereich
  • Mindestens eine App-Rolle

Standardmäßig empfiehlt das Anwendungsregistrierungsportal die Verwendung von api://{clientId} als Ressourcen-URI. Dieser URI ist eindeutig, aber nicht von Menschen lesbar. Wenn Sie den URI ändern, müssen Sie sicherstellen, dass der neue Wert eindeutig ist. Das Anwendungsregistrierungsportal stellt sicher, dass Sie eine konfigurierte Herausgeberdomäne verwenden.

Den Clientanwendungen werden Bereiche als delegierte Berechtigungen und App-Rollen als Anwendungsberechtigungen für Ihre Web-API angezeigt.

Bereiche werden den Benutzern Ihrer App auch im Zustimmungsfenster angezeigt. Geben Sie daher die entsprechenden Zeichenfolgen an, die den Bereich beschreiben:

  • Aus Sicht eines Benutzers
  • Aus Sicht eines Mandantenadministrators, der Administratoreinwilligung erteilen kann

Die Einwilligung zu App-Rollen kann nicht durch einen Benutzer erteilt werden (da sie von einer Anwendung verwendet werden, die die Web-API im eigenen Auftrag aufruft). Ein Mandantenadministrator muss in Clientanwendungen der App-Rollen einwilligen, die Ihre Web-API verfügbar machen. Weitere Informationen finden Sie unter Administratoreinwilligung.

Verfügbarmachen delegierter Berechtigungen (Bereiche)

Um delegierte Berechtigungen bzw. Bereiche (Scopes) verfügbar zu machen, führen Sie die in Konfigurieren einer Anwendung für das Verfügbarmachen einer Web-API beschriebenen Schritte aus.

Wenn Sie das in dieser Artikelreihe beschriebene Web-API-Szenario durcharbeiten, verwenden Sie folgende Einstellungen:

  • Anwendungs-ID-URI: Akzeptieren Sie den vorgeschlagenen Anwendungs-ID-URI (api://< clientId>) (falls Sie dazu aufgefordert werden)
  • Bereichsname: access_as_user
  • Zum Einwilligen berechtigte Personen: Administratoren und Benutzer
  • Anzeigename der Administratorzustimmung: Zugriff auf TodoListService als Benutzer
  • Beschreibung der Administratorzustimmung: Greift als Benutzer auf die TodoListService-Web-API zu
  • Anzeigename der Benutzerzustimmung: Zugriff auf TodoListService als Benutzer
  • Beschreibung der Benutzerzustimmung: Greift als Benutzer auf die TodoListService-Web-API zu
  • Status:Aktiviert

Tipp

Beim Anwendungs-ID-URI haben Sie die Möglichkeit, ihn auf die physische Autorität der API festzulegen, z. B https://graph.microsoft.com. Dies kann hilfreich sein, wenn die URL der API, die aufgerufen werden muss, bekannt ist.

Aufrufen Ihrer Web-API von einem Dienst oder einer Daemon-App

Anstelle delegierter Berechtigungen müssen Sie Anwendungsberechtigungen verfügbar machen, wenn Daemons, Dienste oder andere nicht interaktive Anwendungen (ohne Benutzerinteraktion) auf Ihre API zugreifen sollen. Da Daemon- und dienstartige Anwendungen unbeaufsichtigt ausgeführt werden und sich mit ihrer eigenen Identität authentifizieren, gibt es keinen Benutzer, der Berechtigungen „delegieren“ muss.

Verfügbarmachen von Anwendungsberechtigungen (App-Rollen)

Um Anwendungsberechtigungen verfügbar zu machen, führen Sie die in Hinzufügen von App-Rollen zu Ihrer App beschriebenen Schritte aus.

Wählen Sie im Bereich App-Rolle erstellen unter Zulässige Membertypen die Option Anwendungen aus. Oder fügen Sie die Rolle mithilfe des Anwendungsmanifest-Editors hinzu, wie im Artikel beschrieben.

Einschränken von Zugriffstoken auf bestimmte Client-Apps

App-Rollen sind der Mechanismus, den ein Anwendungsentwickler verwendet, um die Berechtigungen seiner App verfügbar zu machen. Der Code Ihrer Web-API sollte nach App-Rollen in den Zugriffstoken suchen, die er von Aufrufern empfängt.

Um eine weitere Sicherheitsebene hinzuzufügen, kann ein Microsoft Entra-Mandantenadministrator seinen Mandanten so konfigurieren, dass Microsoft Identity Platform Sicherheitstoken nur für die Client-Apps ausgibt, die für den API-Zugriff genehmigt wurden.

Erhöhen der Sicherheit durch Beschränken der Tokenausstellung auf Client-Apps, denen App-Rollen zugewiesen wurden:

  1. Wählen Sie Ihre App im Microsoft Entra Admin Center unter Identität>Anwendungen>App-Registrierungen.
  2. Wählen Sie auf der Übersichtsseite der Anwendung den Link Verwaltete Anwendung in lokalem Verzeichnis aus, um zur Seite Übersicht über Unternehmensanwendungen zu navigieren.
  3. Wählen Sie unter Verwalten die Option Eigenschaften aus.
  4. Legen Sie Zuweisung erforderlich? auf Ja fest.
  5. Wählen Sie Speichern aus.

Microsoft Entra ID sucht nun nach App-Rollenzuweisungen von Clientanwendungen, die Zugriffstoken für Ihre Web-API anfordern. Wenn einer Client-App keine App-Rollen zugewiesen wurden, gibt Microsoft Entra ID eine Fehlermeldung an den Client mit folgendem Wortlaut zurück: invalid_client: AADSTS501051: Anwendung <Anwendungsname> ist keiner Rolle für die <Web-API> zugewiesen.

Warnung

Verwenden Sie KEINE AADSTS-Fehlercodes oder die Zeichenfolgen der Fehlermeldungen als Literale im Code Ihrer Anwendung. Die AADSTS-Fehlercodes und die von Microsoft Entra ID zurückgegebenen Fehlermeldungszeichenfolgen sind nicht unveränderlich und können jederzeit und ohne Ihr Wissen von Microsoft geändert werden. Wenn Sie Verzweigungsentscheidungen in Ihrem Code anhand von AADSTS-Codewerten oder deren Fehlermeldungszeichenfolgen treffen, setzen Sie Funktionalität und Stabilität Ihrer Anwendung aufs Spiel.

Nächste Schritte

App-Codekonfiguration ist der nächste Artikel in dieser Reihe.