Schnellstart: Konfigurieren einer Anwendung für das Verfügbarmachen einer Web-API

  • Artikel

In diesem Schnellstart werden Sie eine Web-API bei der Microsoft-Identitätsplattform registrieren und sie durch Hinzufügen eines Bereichs für Client-Apps verfügbar machen. Indem Sie Ihre Web-API registrieren und über Bereiche verfügbar machen sowie eine Besitzer- und eine App-Rolle zuweisen, können Sie für autorisierte Benutzer*innen und Client-Apps, die auf Ihre API zugreifen, berechtigungsbasierten Zugriff auf die Ressourcen bereitstellen.

Voraussetzungen

Registrieren der Web-API

Für den Zugriff auf APIs müssen Zugriffsbereiche und Rollen konfiguriert werden. Konfigurieren Sie Zugriffsbereiche und Rollen für die API, wenn Sie die Web-APIs Ihrer Ressourcenanwendung für Clientanwendungen verfügbar machen möchten. Konfigurieren Sie Zugriffsberechtigungen für die API in der App-Registrierung, wenn eine Clientanwendung auf eine Web-API zugreifen soll.

Um einen bereichsbezogenen Zugriff auf die Ressourcen in Ihrer Web-API zu ermöglichen, müssen Sie die API zunächst bei Microsoft Identity Platform registrieren.

Führen Sie dazu die Schritte im Abschnitt Registrieren einer Anwendung in Schnellstart: Registrieren einer App bei Microsoft Identity Platform aus.

Überspringen Sie den Abschnitt Umleitungs-URI (optional). Sie müssen keinen Umleitungs-URI für eine Web-API konfigurieren, da keine Benutzer interaktiv angemeldet werden.

Zuweisen eines Anwendungsbesitzers

  1. Wählen Sie in Ihrer App-Registrierung unter Verwalten die Optionen Besitzer und Besitzer hinzufügen aus.
  2. Suchen Sie im neuen Fenster nach den Besitzern, die Sie der Anwendung zuweisen möchten, und wählen Sie sie aus. Ausgewählte Besitzer werden im rechten Bereich angezeigt. Wenn Sie fertig sind, bestätigen Sie mit Auswählen. Die App-Besitzer werden jetzt in der Liste „Besitzer“ angezeigt.

Hinweis

Stellen Sie sicher, dass sowohl die API-Anwendung als auch die Anwendung, der Sie Berechtigungen hinzufügen möchten, über einen Besitzer verfügen. Andernfalls wird die API beim Anfordern von API-Berechtigungen nicht aufgeführt.

Zuweisen einer App-Rolle

  1. Wählen Sie in Ihrer App-Registrierung unter Verwalten die Optionen App-Rollen und App-Rolle erstellen aus.

  2. Geben Sie dann im Bereich App-Rolle erstellen die Attribute der App-Rolle an. Für diese exemplarische Vorgehensweise können Sie die Beispielwerte verwenden oder eigene Werte angeben.

    Feld Beschreibung Beispiel
    Anzeigename Der Name Ihrer App-Rolle Mitarbeiterdatensätze
    Zulässige Mitgliedstypen Angabe, ob die App-Rolle Benutzer*innen/Gruppen und/oder Anwendungen zugewiesen werden kann Anwendungen
    Wert Der im Anspruch „Rollen“ eines Tokens angezeigte Wert Employee.Records
    Beschreibung Eine detailliertere Beschreibung der App-Rolle Anwendungen haben Zugriff auf Mitarbeiterdatensätze

  3. Aktivieren Sie das Kontrollkästchen, um die App-Rolle zu aktivieren.

Wenn die Web-API registriert wurde und ihr eine App-Rolle und ein App-Besitzer zugewiesen wurden, können Sie dem API-Code Bereiche hinzufügen, damit Consumern differenzierte Berechtigungen zugewiesen werden können.

Hinzufügen eines Bereichs

Tipp

Die Schritte in diesem Artikel können je nach dem Portal, mit dem Sie beginnen, geringfügig variieren.

Der Code in einer Clientanwendung fordert die Berechtigung zum Ausführen von Vorgängen an, die von Ihrer Web-API definiert werden, indem er zusammen mit seinen Anforderungen ein Zugriffstoken an die geschützte Ressource (die Web-API) übergibt. Ihre Web-API führt anschließend den angeforderten Vorgang nur dann aus, wenn das empfangene Zugriffstoken die für den Vorgang erforderlichen Bereiche enthält.

Führen Sie zuerst die folgenden Schritte aus, um einen Beispielbereich namens Employees.Read.All zu erstellen:

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Cloudanwendungsadministrator an.

  2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie das Symbol für Einstellungen im oberen Menü, um zum Mandanten zu wechseln, der die App-Registrierung aus dem Menü Verzeichnisse + Abonnements enthält.

  3. Wechseln Sie zu Identität>Anwendungen>App-Registrierungen, und wählen Sie die App-Registrierung Ihrer API aus.

  4. Wählen Sie Eine API verfügbar machen aus.

  5. Wählen Sie Hinzufügen neben Anwendungs-ID-URI aus, falls Sie noch keinen konfiguriert haben.

    Sie können den Standardwert api://<application-client-id> oder ein anderes unterstütztes App-ID-URI-Muster verwenden. Der APP-ID-URI fungiert als Präfix für die Bereiche, auf die Sie in Ihrem API-Code verweisen, und muss global eindeutig sein.

  6. Wählen Sie Bereich hinzufügen aus:

    An app registration's Expose an API pane in the Azure portal

  7. Geben Sie als Nächstes unter Bereich hinzufügen die Attribute des Bereichs an. Für diese exemplarische Vorgehensweise können Sie die Beispielwerte verwenden oder eigene Werte angeben.

    Feld Beschreibung Beispiel
    Bereichsname Name des Bereichs. Eine häufige Benennungskonvention für Bereiche lautet resource.operation.constraint. Employees.Read.All
    Zum Einwilligen berechtigte Personen Gibt an, ob für diesen Bereich die Einwilligung von Benutzern ausreicht oder die Einwilligung eines Administrators erforderlich ist. Wählen Sie für umfassendere Berechtigungen die Option Nur Administratoren. Administratoren und Benutzer
    Anzeigename der Administratoreinwilligung Eine kurze Beschreibung des Zwecks für den Bereich, der nur Administratoren angezeigt wird. Read-only access to Employee records
    Beschreibung der Administratoreinwilligung Eine ausführlichere Beschreibung der vom Bereich gewährten Berechtigung, die nur Administratoren angezeigt wird. Allow the application to have read-only access to all Employee data.
    Anzeigename der Benutzereinwilligung Eine kurze Beschreibung des Zwecks für den Bereich. Wird Benutzern nur angezeigt, wenn Sie unter Zum Einwilligen berechtigte Personen die Option Administratoren und Benutzer festgelegt haben. Read-only access to your Employee records
    Beschreibung der Benutzereinwilligung Eine ausführlichere Beschreibung der Berechtigung, die vom Bereich gewährt wird. Wird Benutzern nur angezeigt, wenn Sie unter Zum Einwilligen berechtigte Personen die Option Administratoren und Benutzer festgelegt haben. Allow the application to have read-only access to your Employee data.

  8. Legen Sie den Status auf Aktiviert fest, und wählen Sie dann Bereich hinzufügen aus.

  9. (Optional) Soll Benutzern Ihrer App keine Einwilligungsaufforderung für die von Ihnen festgelegten Bereiche angezeigt werden, können Sie die Clientanwendung für den Zugriff auf Ihre Web-API vorab autorisieren. Sie sollten nur die Clientanwendungen vorab autorisieren, denen Sie vertrauen, da Ihre Benutzer keine Möglichkeit haben, ihre Einwilligung zu verweigern.

    1. Wählen Sie unter Autorisierte Clientanwendungen die Option Eine Clientanwendung hinzufügen aus.
    2. Geben Sie den Wert für Anwendungs-ID (Client) der Clientanwendung ein, die Sie vorab autorisieren möchten, beispielsweise den einer zuvor registrierten Webanwendung.
    3. Wählen Sie unter Autorisierte Bereichedie Bereiche aus, für die Sie die Einwilligungsaufforderung unterdrücken möchten, und wählen Sie dann Anwendung hinzufügen aus.

    Wenn Sie diesen optionalen Schritt ausgeführt haben, ist die Client-App jetzt eine vorab autorisierte Client-App, und Benutzer werden bei der Anmeldung nicht zur Einwilligung aufgefordert.

Fügen Sie als Nächstes einen weiteren Beispielbereich namens Employees.Write.All mit ausschließlich Administratoreinwilligung hinzu. Bereiche, die Administratoreinwilligung erfordern, werden in der Regel für den Zugriff auf Vorgänge mit höheren Berechtigungen verwendet. Außerdem werden sie häufig von Clientanwendungen verwendet, die als Back-End-Dienste oder Daemons ausgeführt werden und keine Benutzer interaktiv anmelden.

Um den Beispielbereich Employees.Write.All hinzuzufügen, führen Sie die im Abschnitt Hinzufügen eines Bereichs beschriebenen Schritte aus, und geben Sie unter Bereich hinzufügen die folgenden Werte an:

Feld Beispielwert
Bereichsname Employees.Write.All
Zum Einwilligen berechtigte Personen Nur Administratoren
Anzeigename der Administratoreinwilligung Write access to Employee records
Beschreibung der Administratoreinwilligung Allow the application to have write access to all Employee data.
Anzeigename der Benutzereinwilligung Keine (Feld leer lassen)
Beschreibung der Benutzereinwilligung Keine (Feld leer lassen)

Legen Sie den Status auf Aktiviert fest, und wählen Sie dann Bereich hinzufügen aus.

Überprüfen der verfügbar gemachten Bereiche

Wenn Sie beide in den vorherigen Abschnitten beschriebenen Beispielbereiche erfolgreich hinzugefügt haben, werden sie im Bereich Verfügbarmachen einer API der App-Registrierung Ihrer Web-API angezeigt, ähnlich wie in der folgenden Abbildung:

Screenshot of the Expose an API pane showing two exposed scopes.

Wie aus der Abbildung hervorgeht, wird die vollständige Zeichenfolge eines Bereichs durch die Verkettung von Anwendungs-ID-URI der Web-API und Bereichsname des Bereichs gebildet.

Wenn der Anwendungs-ID-URI Ihrer Web-API also beispielsweise https://contoso.com/api und der Bereichsname Employees.Read.All lautet, ergibt sich daraus die folgende Zeichenfolge für den vollständigen Bereich:

https://contoso.com/api/Employees.Read.All

Verwenden der verfügbar gemachten Bereiche

Im nächsten Artikel dieser Serie konfigurieren Sie die Registrierung einer Client-App mit Zugriff auf Ihre Web-API und den von Ihnen definierten Bereichen, indem Sie die Schritte in diesem Artikel ausführen.

Sobald der Registrierung einer Client-App die Berechtigung für den Zugriff auf Ihre Web-API erteilt wurde, kann dem Client ein OAuth 2.0-Zugriffstoken durch die Identitätsplattform ausstellt werden. Wenn der Client die Web-API aufruft, präsentiert er ein Zugriffstoken, dessen Bereichs(scp)-Anspruch auf die Berechtigungen festgelegt ist, die Sie in der Client-App-Registrierung angegeben haben.

Sie können später bei Bedarf zusätzliche Bereiche verfügbar machen. Beachten Sie, dass Ihre Web-API mehrere Bereiche verfügbar machen kann, die verschiedenen Vorgängen zugeordnet sind. Ihre Ressource kann zur Laufzeit den Zugriff auf die Web-API steuern, indem die Ansprüche für den Bereich (scp) im erhaltenen OAuth 2.0-Zugriffstoken ausgewertet werden.

Nächste Schritte

Nachdem Sie nun Ihre Web-API durch Konfigurieren der Bereiche verfügbar gemacht haben, konfigurieren Sie die Registrierung Ihrer Client-App mit der Zugriffsberechtigung für diese Bereiche.

Schnellstart: Konfigurieren einer Clientanwendung für den Zugriff auf Web-APIs