Schutz von APIs

  • 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 Registrierung, Definieren von Berechtigungen sowie Zustimmung und Erzwingen 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 definieren Sie, wie aufrufende Anwendungen auf Ihre API und ihre delegierten und Anwendungsberechtigungen verweisen. 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 verfügbar macht.

Normalerweise führt eine API keine Authentifizierung durch und fordert die Autorisierung auch nicht direkt an. Die API überprüft ein Token, das von der aufrufenden App präsentiert wird. APIs verfügen nicht über interaktive Anmeldungen, daher müssen Sie keine Einstellungen wie Umleitungs-URI oder Anwendungstyp registrieren. 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, der als Anwendungs-ID-URI bezeichnet wird, damit Client-Apps, die auf Ihre API zugreifen müssen, die Berechtigung zum Aufrufen Ihrer API anfordern. 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 Berechtigungen

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 eine Administratoreinwilligung erforderlich ist, erfordert die Berechtigung immer die Administratoreinwilligung.

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 der Benutzer über die Berechtigung auswählen kann, welche Anwendung nur auf seine eigenen Informationen zugreifen kann, kann die Einwilligung des Benutzers angemessen sein. 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 der Anwendungsberechtigungen

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

Wie bei delegierten Berechtigungen stellen Sie präzise Anwendungsberechtigungen bereit, sodass Workloads, die Ihre API aufrufen, den geringsten Berechtigungszugriff einhalten und den Zero Trust-Prinzipien entsprechen können. 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 überprüfen und interpretieren, die aufrufende Anwendungen als Bearertoken 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 oder Passport, wenn Sie einen Knoten erstellen) verwenden die richtigen Schritte und verringern sie für 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 überprüfen, erhalten sie unsere veröffentlichte Liste der öffentlichen Signaturschlüssel aus 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 überprüft haben, überprüft Ihre API die Ansprüche im Token, um zu bestimmen, wie es 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 zum Zuweisen von Benutzern und Gruppen definiert hat, lassen Sie die API auf rollenbezogene Ansprüche im Token und entsprechendes Verhalten prüfen. Für Anwendungsberechtigungstoken gibt es keinen bereichsbezogenen (scp) Anspruch. Lassen Sie stattdessen die API festlegen, welche Anwendungsberechtigungen der Workload erhalten hat, indem Sie den Rollenanspruch prüfen.

Nachdem Ihre API das Token und die Bereiche überprüft 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