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

In dieser Schnellstartanleitung registrieren Sie eine Web-API bei Microsoft Identity Platform und machen sie durch Hinzufügen eines Beispielbereichs für Client-Apps verfügbar. Indem Sie Ihre Web-API registrieren und über Bereiche verfügbar machen, können Sie für autorisierte Benutzer und Client-Apps, die auf Ihre API zugreifen, einen berechtigungsbasierten Zugriff auf die Ressourcen bereitstellen.

Voraussetzungen

Registrieren der Web-API

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.

  1. Führen Sie dazu die Schritte im Abschnitt Registrieren einer Anwendung in Schnellstart: Registrieren einer App bei Microsoft Identity Platform aus.
  2. Überspringen Sie die Abschnitte Hinzufügen eines Umleitungs-URIs und Konfigurieren von Plattformeinstellungen. Sie müssen keinen Umleitungs-URI für eine Web-API konfigurieren, da keine Benutzer interaktiv angemeldet werden.
  3. Überspringen Sie vorerst den Abschnitt Hinzufügen von Anmeldeinformationen. Ihre API würde nur eigene Anmeldeinformationen benötigen, wenn sie auf eine Downstream-API zugreifen müsste. Ein solches Szenario wird in diesem Artikel nicht behandelt.

Nachdem Sie Ihre Web-API registriert haben, können Sie die Bereiche hinzufügen, mit denen der Code Ihrer API eine differenzierte Berechtigung für Nutzer Ihrer API bereitstellen kann.

Hinzufügen eines Bereichs

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

  2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie im oberen Menü den Filter Verzeichnis + Abonnement , um den Mandanten auszuwählen, der die Registrierung der Client-App enthält.

  3. Wählen Sie zuerst Azure Active Directory>App-Registrierungen und dann die App-Registrierung Ihrer API aus.

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

  5. Wählen Sie Festlegen 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)

Überprüfen der verfügbar gemachten Bereiche

Wenn Sie die beiden in den vorherigen Abschnitten beschriebenen Beispielbereiche erfolgreich hinzugefügt haben, werden sie, ähnlich wie in der folgenden Abbildung gezeigt, im Bereich Eine API verfügbar machen der App-Registrierung Ihrer Web-API angezeigt:

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

Nachdem der Registrierung einer Client-App die Berechtigung für den Zugriff auf Ihre Web-API erteilt wurde, kann Microsoft Identity Platform für den Client ein OAuth 2.0-Zugriffstoken ausstellen. 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 durch Auswerten der Bereichs(scp)-Ansprüche im erhaltenen OAuth 2.0-Zugriffstoken den Zugriff auf die Web-API steuern.

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.