Freigeben über

API-Schutz

  • Artikel

Wenn Sie als Entwickler Ihre API schützen, liegt der Fokus auf der Autorisierung. Um die API Ihrer Ressource aufzurufen, müssen Anwendungen die Anwendungsautorisierung erwerben. Die Ressource selbst muss die Autorisierung erzwingen. In diesem Artikel erfahren Sie mehr über bewährte Methoden zum Schutz Ihrer API durch die Registrierung, die Definition von Berechtigungen und Zustimmungen sowie die Erzwingung des Zugriffs, um Ihre Zero Trust-Ziele zu erreichen.

Registrieren Ihrer geschützten API

Um Ihre API mit Microsoft Entra ID zu schützen, müssen Sie Ihre API zuerst registrieren.Anschließend können Sie Ihre registrierten APIs verwalten. In Microsoft Entra ID ist eine API eine App mit bestimmten App-Registrierungseinstellungen, die sie als Ressource oder API definieren, auf die eine andere Anwendung für den Zugriff autorisiert werden kann. Im Microsoft Entra Admin Center sind Microsoft Identity Developer, App-Registrierungen, APIs, die im Mandanten als Branchen-APIs oder Dienste von SaaS-Anbietern sind, die über APIs verfügen, die von Microsoft Entra ID geschützt werden.

Während der Registrierung legen Sie fest, wie aufrufende Anwendungen Ihre API und ihre delegierten und Anwendungsberechtigungen referenzieren. Eine App-Registrierung kann eine Lösung darstellen, die sowohl Clientanwendungen als auch APIs enthält. In diesem Artikel befassen wir uns jedoch mit dem Szenario, in dem eine eigenständige Ressource eine API bereitstellt.

Normalerweise führt eine API keine Authentifizierung durch und fordert die Autorisierung auch nicht direkt an. Die API validiert ein Token, das die aufrufende Anwendung vorgibt. Bei APIs gibt es keine interaktiven Anmeldungen, so dass Sie keine Einstellungen wie Redirect URI oder Anwendungstyp registrieren müssen. APIs erhalten ihre Token aus den Anwendungen, die die APIs aufrufen, nicht durch Interaktion mit Microsoft Entra ID. Verwenden Sie für Web-APIs OAuth2-Zugriffstoken für die Autorisierung. Web-APIs überprüfen Bearertoken, um Aufrufer zu autorisieren. Akzeptieren Sie keine ID-Token als Berechtigungsnachweis.

Standardmäßig fügt Microsoft Entra ID User.Read den API-Berechtigungen einer neuen App-Registrierung hinzu. Sie entfernen diese Berechtigung für die meisten Web-APIs. Microsoft Entra ID erfordert API-Berechtigungen nur, wenn eine API eine andere API aufruft. Wenn Ihre API keine andere API aufruft, entfernen Sie die User.Read Berechtigung, wenn Sie Ihre API registrieren.

Sie benötigen einen eindeutigen Bezeichner für Ihre API, die so genannte Anwendungs-ID URI, die Clientanwendungen, die auf Ihre API zugreifen müssen, um Erlaubnis bitten, Ihre API aufzurufen. Der Anwendungs-ID-URI muss für alle Microsoft Entra-Mandanten eindeutig sein. Sie können api://<clientId> (den Standardvorschlag im Portal) verwenden, wobei <clientId> die Anwendungs-ID Ihrer registrierten API ist.

Um Entwicklern, die Ihre API aufrufen, einen benutzerfreundlicheren Namen bereitzustellen, können Sie die Adresse Ihrer API als Anwendungs-ID-URI verwenden. Sie können beispielsweise https://API.yourdomain.com verwenden, wobei yourdomain.com eine konfigurierte Herausgeberdomäne in Ihrem Microsoft Entra-Mandanten sein muss. Microsoft überprüft, ob Sie Eigentümer der Domäne sind, damit Sie sie als eindeutigen Bezeichner für Ihre API verwenden können. Sie müssen an dieser Adresse keinen Code haben. Die API kann überall dort sein, wo sie sein soll, es empfiehlt sich jedoch, die HTTPS-Adresse der API als Anwendungs-ID-URI zu verwenden.

Definieren delegierter Berechtigungen mit geringsten Rechten

Wenn Ihre API von Anwendungen aufgerufen wird, die Benutzer haben, müssen Sie mindestens eine delegierte Berechtigung definieren (siehe Hinzufügen eines Bereichs bei der App-Registrierung Eine API verfügbar machen).

APIs, die Zugriff auf Organisationsdatenspeicher ermöglichen, können die Aufmerksamkeit von Angreifern wecken, die auf diese Daten zugreifen möchten. Statt nur eine delegierte Berechtigung zu haben, entwerfen Sie Ihre Berechtigungen nach dem Zero Trust-Prinzip des geringsten Berechtigungszugriffs. Es kann schwierig sein, später in ein Modell mit den geringsten Berechtigungen zu wechseln, wenn alle Client-Apps mit voll privilegiertem Zugriff beginnen.

Häufig fallen Entwickler in ein Muster der Verwendung einer einzigen Berechtigung wie „Zugriff als Benutzer” oder „Benutzeridentitätswechsel” (ein gängiger Ausdruck, obwohl technisch ungenau). Einzelne Berechtigungen wie diese ermöglichen nur den vollständigen privilegierten Zugriff auf Ihre API.

Deklarieren Sie die geringsten Berechtigungsbereiche, damit Ihre Anwendungen nicht anfällig für Kompromittierungen sind oder zum Ausführen einer Aufgabe verwendet werden, die Sie nie beabsichtigt haben. Definieren Sie mehrere Bereiche in API-Berechtigungen. Trennen Sie beispielsweise Bereiche vom Lesen und Aktualisieren von Daten und erwägen Sie, schreibgeschützte Berechtigungen anzubieten. Schreibzugriff beinhaltet Berechtigungen für Erstellungs-, Aktualisierungs- und Löschvorgänge. Ein Client sollte niemals Schreibzugriff auf reine Lesedaten benötigen.

Erwägen Sie die Verwendung von Standard- und Vollzugriffsberechtigungen, wenn Ihre API mit vertraulichen Daten arbeitet. Beschränken Sie die vertraulichen Eigenschaften so, dass eine Standardberechtigung keinen Zugriff zulässt (z. B Resource.Read). Implementieren Sie dann eine Vollzugriffsberechtigung (etwa Resource.ReadFull), die alle verfügbaren Eigenschaften und vertraulichen Informationen zurückgibt.

Werten Sie immer die angeforderten Berechtigungen aus, um sicherzustellen, dass Sie den Satz mit den geringstmöglichen Berechtigungen für die jeweilige Aufgabe anfordern. Vermeiden Sie das Anfordern höherer Berechtigungen. Erstellen Sie stattdessen eine individuelle Berechtigung für jedes Kernszenario. Weitere Beispiele für diesen Ansatz finden Sie unter Microsoft Graph-Berechtigungsreferenz. Suchen und verwenden Sie nur die richtige Anzahl von Berechtigungen, um Ihre Anforderungen zu erfüllen.

Entscheiden Sie als Teil Ihrer Bereichsdefinitionen, ob der Bereich des Vorgangs, der mit einem bestimmten Bereich ausgeführt werden kann, eine Administratorzustimmung erfordert.

Als API-Designer können Sie Anleitungen dazu bereitstellen, welche Bereiche sicher nur die Einwilligung des Benutzers erfordern können. Mandantenadministratoren können jedoch einen Mandanten so konfigurieren, dass alle Berechtigungen die Administratoreinwilligung erfordern. Wenn Sie einen Bereich so definieren, dass die Admin-Genehmigung erforderlich ist, erfordert die Berechtigung immer die Admin-Genehmigung.

Bei der Entscheidung über die Einwilligung von Benutzern oder Administratoren gibt es zwei Dinge zu beachten:

  1. Ob sich der Bereich der Vorgänge hinter der Berechtigung auf mehr als einen einzelnen Benutzer auswirkt. Wenn die Benutzerin oder der Benutzer wählen kann, welche Anwendung nur auf die eigenen Daten zugreifen darf, ist die Zustimmung der Benutzerin oder des Benutzers möglicherweise angemessen. Beispielsweise kann der Benutzer zustimmen, seine bevorzugte Anwendung für E-Mails auszuwählen. Wenn die Vorgänge hinter der Berechtigung jedoch mehr als einen einzelnen Benutzer umfassen (z. B. vollständige Benutzerprofile anderer Benutzer anzeigen), definieren Sie diese Berechtigung als erforderliche Administratorzustimmung.

  2. Gibt an, ob der Bereich der Vorgänge hinter der Berechtigung einen breiten Umfang hat. Beispielsweise ist ein breiter Bereich, wenn eine Berechtigung einer App ermöglicht, alles in einem Mandanten zu ändern oder etwas zu tun, das unumkehrbar sein könnte. Ein breiter Bereich gibt an, dass Sie eine Administratoreinwilligung anstelle der Benutzereinwilligung benötigen.

Gehen Sie eher konservativ vor, und erfordern Sie die Einwilligung des Administrators, wenn Sie Zweifel haben. Beschreiben Sie klar und präzise die Folgen der Einwilligung in Ihren Berechtigungszeichenfolgen. Gehen Sie davon aus, dass die Person, die Ihre Beschreibungszeichenfolgen liest, mit Ihren APIs oder Produkten nicht vertraut ist.

Vermeiden Sie das Hinzufügen Ihrer APIs zu vorhandenen Berechtigungen auf eine Weise, die die Semantik der Berechtigung ändert Das Überladen vorhandener Berechtigungen weicht die Begründung auf, für die Clients zuvor eine Einwilligung erteilt haben.

Definieren von Anwendungsberechtigungen

Wenn Sie Nichtbenutzeranwendungen erstellen, verfügen Sie nicht über ein Benutzerkonto, das Sie zur Eingabe eines Benutzernamens und Kennworts oder einer mehrstufigen Authentifizierung (Multifactor Authentication, MFA) auffordern können. Wenn Anwendungen ohne Benutzer (z. B. Workloads, Dienste und Daemons) Ihre API aufrufen, müssen Sie Anwendungsberechtigungen für Ihre API definieren. Wenn Sie eine Anwendungsberechtigung definieren, verwenden Sie eine Anwendungsrolle anstelle von Bereichen.

Wie bei delegierten Berechtigungen stellen Sie granulare Anwendungsberechtigungen bereit, so dass Workloads, die Ihre API aufrufen, dem Zugriff mit den geringsten Rechten folgen können und den Zero Trust-Prinzipien entsprechen. Vermeiden Sie, nur eine App-Rolle (App-Berechtigung) und einen Bereich (delegierte Berechtigung) zu veröffentlichen oder alle Vorgänge für jeden Client verfügbar zu machen.

Workloads authentifizieren sich mit Clientanmeldeinformationen und fordern ein Token mithilfe des .defaultBereichs an, wie im folgenden Beispielcode veranschaulicht.

// With client credentials flows the scopes is ALWAYS of the shape "resource/.default", as the 
// application permissions need to be set statically (in the portal or by PowerShell), 
// and then granted by a tenant administrator
string[] scopes = new string[] { "https://kkaad.onmicrosoft.com/webapi/.default" };
 
AuthenticationResult result = null;
try
{
  result = await app.AcquireTokenForClient(scopes)
    .ExecuteAsync();
  Console.WriteLine("Token acquired \n");
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
  // Invalid scope. The scope has to be of the form "https://resourceurl/.default"
  // Mitigation: change the scope to be as expected
  Console.WriteLine("Scope provided is not supported");
}

Berechtigungen erfordern Administratoreinwilligung, wenn kein Benutzer vor der App vorhanden ist und wenn die Anwendungsberechtigung eine breite Palette von Vorgängen ermöglicht.

Zugriff erzwingen

Stellen Sie sicher, dass Ihre APIs den Zugriff erzwingen, indem sie Zugriffstoken validieren und interpretieren, die die aufrufenden Anwendungen als Inhaber-Token im Autorisierungsheader der HTTPS-Anforderung bereitstellen. Sie können den Zugriff erzwingen, indem Sie Token überprüfen, Metadatenaktualisierungen verwalten und Bereiche und Rollen erzwingen, wie in den folgenden Abschnitten beschrieben.

Überprüfen von Token

Nachdem Ihre API ein Token empfängt, muss sie das Token überprüfen. Die Überprüfung stellt sicher, dass das Token vom richtigen Aussteller als unmanipuliert und unverändert stammt. Überprüfen Sie die Signatur, da Sie das Token nicht direkt aus der Microsoft Entra ID erhalten, wie Sie es bei ID-Token tun. Überprüfen Sie die Signatur, nachdem Ihre API ein Token von einer nicht vertrauenswürdigen Quelle im Netzwerk empfängt.

Da es bekannte Sicherheitsrisiken bei der Überprüfung der JSON-Webtokensignatur gibt, verwenden Sie eine gute und etablierte Standardtoken-Überprüfungsbibliothek. Authentifizierungsbibliotheken (z. B. Microsoft.Identity.Web) verwenden die richtigen Schritte, und verringern Sie bekannte Sicherheitsrisiken.

Optional erweitern Sie die Tokenüberprüfung. Verwenden Sie den Mandanten-ID (tid)-Anspruch, um die Mandanten einzuschränken, in denen Ihre API ein Token abrufen kann. Verwenden Sie die Ansprüche azp und appid, um Apps zu filtern, die Ihre API aufrufen können. Verwenden Sie den Anspruch der Objekt-ID (oid), um den Zugriff auf einzelne Benutzer zu begrenzen.

Verwalten der Metadatenaktualisierung

Stellen Sie immer sicher, dass Ihre Tokenüberprüfungsbibliothek die erforderlichen Metadaten effektiv verwaltet. In diesem Fall sind die Metadaten die öffentlichen Schlüssel, das Paar privater Schlüssel, die Microsoft zum Signieren von Microsoft Entra-Token verwendet. Wenn Ihre Bibliotheken diese Token validieren, erhalten sie unsere veröffentlichte Liste der öffentlichen Signierschlüssel von einer bekannten Internetadresse. Stellen Sie sicher, dass die Hostingumgebung über das richtige Timing verfügt, um diese Schlüssel abzurufen.

Beispielsweise wurden ältere Bibliotheken gelegentlich hartcodiert, um diese öffentlichen Signaturschlüssel alle 24 Stunden zu aktualisieren. Überlegen Sie sich, wann die Microsoft Entra-ID diese Schlüssel schnell rotieren muss, und die von Ihnen heruntergeladenen Schlüssel haben die neuen rotierten Schlüssel nicht enthalten. Ihre API könnte für einen Tag offline sein, während sie auf den Aktualisierungszyklus der Metadaten wartet. Verweisen Sie auf spezifische Metadatenaktualisierungsanleitungen, um sicherzustellen, dass die Metadaten ordnungsgemäß abgerufen werden. Wenn Sie eine Bibliothek verwenden, stellen Sie sicher, dass diese Metadaten innerhalb eines angemessenen Zeitrahmens verarbeitet werden.

Erzwingen von Bereichen und Rollen

Nachdem Sie Ihr Token validiert haben, prüft Ihre API die Angaben im Token, um festzustellen, wie sie funktionieren soll.

Überprüfen Sie bei delegierten Berechtigungstoken den Bereichsanspruch (scp) Ihrer API, um zu sehen, welche Einwilligung die Anwendung gegeben hat. Überprüfen Sie die Ansprüche der Objekt-ID (oid) oder der Subjektschlüssels (sub), um den Benutzer anzuzeigen, in dessen Auftrag die Anwendung arbeitet.

Vergewissern Sie sich dann, dass der Benutzer auch Zugriff auf den angeforderten Vorgang hat. Wenn Ihre API Rollen für die Zuweisung an Benutzerinnen und Benutzer und Gruppen definiert, lassen Sie Ihre API auf Rollenansprüche im Token prüfen und sich entsprechend verhalten. Anwendungsberechtigungstoken verfügen nicht über einen Bereichsanspruch (scp). Lassen Sie stattdessen Ihre API den Rollenanspruch untersuchen, um festzustellen, welche Anwendungsberechtigungen die Workload erhalten hat.

Nachdem Ihre API das Token und die Bereiche validiert und die Objekt-ID (oid), den Subjektschlüssel (sub) und die Rollenansprüche verarbeitet hat, kann Ihre API die Ergebnisse zurückgeben.

Nächste Schritte