Offenlegen von Reichweiten in einer geschützten Web-API

Gilt für: Mitarbeiter(-)Mandanten (weitere Informationen)

In diesem Artikel wird erläutert, wie Sie einer Anwendung Bereiche für eine geschützte Web-API hinzufügen.

Voraussetzungen

• Registrieren Sie eine neue App im Microsoft Entra Admin Center, die nur für Konten in diesem Organisationsverzeichnis konfiguriert ist. Weitere Informationen finden Sie unter Registrieren einer Anwendung . Notieren Sie die folgenden Werte auf der Anwendungsübersichtsseite für die spätere Verwendung:
  • Anwendungs-ID (Client)
  • Verzeichnis-ID (Mandant)

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

App-Rollen können nicht von einem Benutzer zugestimmt werden (da sie von einer Anwendung verwendet werden, die die Web-API im Namen von sich selbst aufruft). Ein Mandantenadministrator muss den Clientanwendungen Ihrer Web-API zustimmen, die App-Rollen offenlegen. 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

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 Diensttypanwendungen unbeaufsichtigt ausgeführt werden und sich mit ihrer eigenen Identität anmelden, gibt es keinen Benutzer, der seine Berechtigungen delegieren könnte.

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 konfigurieren, sodass die Microsoft Identity Platform Sicherheitstoken nur für die Client-Apps ausgibt, die der Mandantenadministrator für den API-Zugriff genehmigt hat.

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

1. Wählen Sie im Microsoft Entra Admin Center Ihre App unter Entra> aus.
2. Suchen und wählen Sie auf der Übersichtsseite der Anwendung unter Essentials den Link Verwaltete Anwendung in lokalem Verzeichnis, 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 zurück, ähnlich wie _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_.

Nächster Schritt

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