Freigeben über

Autorisierung und Rollen im Daten-API-Generator

  • Artikel

Der Daten-API-Generator verwendet einen rollenbasierten Autorisierungsworkflow. Jede eingehende Anforderung, die authentifiziert ist oder nicht, wird einer Rolle zugewiesen. Rollen können Systemrollen oder Benutzerrollen sein. Die zugewiesene Rolle wird dann anhand der in der Konfigurationsdatei angegebenen definierten Berechtigungen überprüft, um zu verstehen, welche Aktionen, Felder und Richtlinien für diese Rolle für die angeforderte Entität verfügbar sind.

Rollen

Rollen legen den Berechtigungskontext fest, in dem eine Anforderung ausgeführt werden soll. Für jede in der Laufzeitkonfiguration definierte Entität können Sie einen Satz von Rollen und zugeordneten Berechtigungen definieren, die bestimmen, wie auf die Entität sowohl im REST- als auch in GraphQL-Endpunkten zugegriffen werden kann.

Der Daten-API-Generator wertet Anforderungen im Kontext einer einzelnen Rolle aus:

  • anonymous , wenn kein Zugriffstoken angezeigt wird.
  • authenticated , wenn ein gültiges Zugriffstoken angezeigt wird.
  • <CUSTOM_USER_ROLE> , wenn ein gültiges Zugriffstoken angezeigt wird und der X-MS-API-ROLE HTTP-Header enthalten ist, indem eine Benutzerrolle angegeben wird, die ebenfalls im Anspruch des Zugriffstokens roles enthalten ist.

Rollen sind nicht additiv. Dies bedeutet, dass ein Benutzer, der Beidem Role1 angehört und Role2 nicht die Berechtigungen erbt, die beiden Rollen zugeordnet sind.

Systemrollen

Systemrollen sind integrierte Rollen, die vom Daten-API-Generator erkannt werden. Eine Systemrolle wird einem Anforderer automatisch zugewiesen, unabhängig von der Rollenmitgliedschaft des Anforderers, die in seinen Zugriffstoken angegeben ist. Es gibt zwei Systemrollen: anonymous und authenticated.

Anonyme Systemrolle

Die anonymous Systemrolle wird Anforderungen zugewiesen, die von nicht authentifizierten Benutzern ausgeführt werden. Durch die Laufzeitkonfiguration definierte Entitäten müssen Berechtigungen für die anonymous Rolle enthalten, wenn nicht authentifizierter Zugriff gewünscht wird.

Beispiel

Die folgende Laufzeitkonfiguration des Daten-API-Generators veranschaulicht die explizite Konfiguration der Systemrolle anonymous , um Lesezugriff auf die Book-Entität einzuschließen:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ]
        }
    ]
}

Wenn eine Clientanwendung eine Anforderung sendet, die im Namen eines nicht authentifizierten Benutzers auf die Book-Entität zugreift, sollte die App den HTTP-Header nicht enthalten Authorization .

Authentifizierte Systemrolle

Die authenticated Systemrolle wird Anforderungen zugewiesen, die von authentifizierten Benutzern ausgeführt werden.

Beispiel

Die folgende Laufzeitkonfiguration des Daten-API-Generators veranschaulicht die explizite Konfiguration der Systemrolle authenticated , um Lesezugriff auf die Book-Entität einzuschließen:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "authenticated",
            "actions": [ "read" ]
        }
    ]
}

Benutzerrollen

Benutzerrollen sind Nichtsystemrollen, die Benutzern innerhalb des Identitätsanbieters zugewiesen werden, den Sie in der Laufzeitkonfiguration festgelegt haben. Damit der Daten-API-Generator eine Anforderung im Kontext einer Benutzerrolle auswerten kann, müssen zwei Anforderungen erfüllt sein:

  1. Das von der Client-App bereitgestellte Zugriffstoken muss Rollenansprüche enthalten, die die Rollenmitgliedschaft eines Benutzers auflisten.
  2. Die Client-App muss den HTTP-Header X-MS-API-ROLE mit Anforderungen enthalten und den Wert des Headers als gewünschte Benutzerrolle festlegen.

Beispiel für die Rollenauswertung

Im folgenden Beispiel werden Anforderungen an die Entität veranschaulicht, die Book in der Laufzeitkonfiguration des Daten-API-Generators konfiguriert ist:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ]
        },
        {
            "role": "authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

In Static Web Apps ist ein Benutzer standardmäßig Mitglied der anonymen Rolle. Wenn der Benutzer authentifiziert ist, ist der Benutzer Mitglied der anonymous Rollen und authenticated .

Wenn eine Client-App eine authentifizierte Anforderung an den Daten-API-Generator sendet, der mit Static Web Apps Datenbankverbindungen (Vorschau) bereitgestellt wird, stellt die Client-App ein Zugriffstoken bereit, das Static Web Apps in JSON transformiert:

{
  "identityProvider": "azuread",
  "userId": "d75b260a64504067bfc5b2905e3b8182",
  "userDetails": "username",
  "userRoles": ["anonymous", "authenticated", "author"]
}

Da der Daten-API-Generator Anforderungen im Kontext einer einzelnen Rolle auswertet, wertet er die Anforderung standardmäßig im Kontext der Systemrolle authenticated aus.

Wenn die Anforderung der Clientanwendung auch den HTTP-Header X-MS-API-ROLE mit dem Wert authorenthält, wird die Anforderung im Kontext der author Rolle ausgewertet. Eine Beispielanforderung, die ein Zugriffstoken und X-MS-API-ROLE einen HTTP-Header enthält:

curl -k -r GET -H 'Authorization: Bearer ey...' -H 'X-MS-API-ROLE: author' https://localhost:5001/api/Book

Wichtig

Die Anforderung einer Client-App wird abgelehnt, wenn der Anspruch des angegebenen Zugriffstokens roles nicht die im X-MS-API-ROLE Header aufgeführte Rolle enthält.

Berechtigungen

Berechtigungen beschreiben:

  • Wer kann Anforderungen an eine Entität basierend auf der Rollenmitgliedschaft stellen?
  • Welche Aktionen (Erstellen, Lesen, Aktualisieren, Löschen, Ausführen) kann ein Benutzer ausführen?
  • Auf welche Felder kann für eine bestimmte Aktion zugegriffen werden?
  • Welche zusätzlichen Einschränkungen gelten für die von einer Anforderung zurückgegebenen Ergebnisse?

Die Syntax zum Definieren von Berechtigungen wird im Artikel zur Laufzeitkonfiguration beschrieben.

Wichtig

Es können mehrere Rollen innerhalb der Berechtigungskonfiguration einer einzelnen Entität definiert sein. Eine Anforderung wird jedoch nur im Kontext einer einzelnen Rolle ausgewertet:

  • Standardmäßig entweder die Systemrolle anonymous oder authenticated
  • Wenn sie eingeschlossen ist, wird die Rolle im X-MS-API-ROLE HTTP-Header festgelegt.

Standardmäßig sicher

Standardmäßig sind für eine Entität keine Berechtigungen konfiguriert, was bedeutet, dass niemand auf die Entität zugreifen kann. Darüber hinaus ignoriert der Daten-API-Generator Datenbankobjekte, wenn in der Laufzeitkonfiguration nicht auf sie verwiesen wird.

Berechtigungen müssen explizit konfiguriert werden.

Um nicht authentifizierten Zugriff auf eine Entität zuzulassen, muss die anonymous Rolle explizit in den Berechtigungen der Entität definiert werden. Beispielsweise werden die Berechtigungen der book Entität explizit festgelegt, um nicht authentifizierten Lesezugriff zuzulassen:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "anonymous",
    "actions": [ "read" ]
  }]
}

Um die Berechtigungsdefinition für eine Entität zu vereinfachen, gehen Sie davon aus, dass die für die authenticated Rolle definierten Berechtigungen verwendet werden, wenn keine spezifischen Berechtigungen für die anonymous Rolle vorhanden sind. Die book zuvor gezeigte Konfiguration ermöglicht es jedem anonymen oder authentifizierten Benutzer, Lesevorgänge für die book Entität auszuführen.

Wenn Lesevorgänge nur auf authentifizierte Benutzer beschränkt werden sollen, sollte die folgende Berechtigungskonfiguration festgelegt werden, was zur Ablehnung nicht authentifizierter Anforderungen führt:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "authenticated",
    "actions": [ "read" ]
  }]
}

Eine Entität erfordert und ist nicht mit Berechtigungen für die anonymous Rollen und authenticated vorkonfiguriert. Eine oder mehrere Benutzerrollen können innerhalb der Berechtigungskonfiguration einer Entität definiert werden, und allen anderen undefinierten Rollen( system- oder benutzerdefiniert) wird automatisch der Zugriff verweigert.

Im folgenden Beispiel ist die Benutzerrolle administrator die einzige definierte Rolle für die book Entität. Ein Benutzer muss Mitglied der administrator Rolle sein und diese Rolle in den X-MS-API-ROLE HTTP-Header einschließen, um mit der book Entität arbeiten zu können:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "administrator",
    "actions": [ "*" ]
  }]
}

Hinweis

Um die Zugriffssteuerung für GraphQL Abfragen bei Verwendung des Daten-API-Generators mit Azure Cosmos DB zu erzwingen, müssen Sie die -Anweisung in der @authorize angegebenen GraphQL Schemadatei verwenden. Für GraphQL Mutationen und Filter in GraphQL Abfragen wird die Zugriffssteuerung jedoch weiterhin durch die zuvor beschriebene Berechtigungskonfiguration erzwungen.

Aktionen

Aktionen beschreiben die Barrierefreiheit einer Entität innerhalb des Bereichs einer Rolle. Aktionen können einzeln oder mit der Platzhalterverknüpfung * (Sternchen) angegeben werden. Die Wildcardverknüpfung stellt alle Aktionen dar, die für den Entitätstyp unterstützt werden:

  • Tabellen und Sichten: create, read, update, delete
  • Gespeicherte Prozeduren: execute

Weitere Informationen zu Aktionen finden Sie in der Dokumentation zur Konfigurationsdatei .

Feldzugriff

Sie können konfigurieren, auf welche Felder für eine Aktion zugegriffen werden soll. Sie können beispielsweise festlegen, welche Felder in die read Aktion eingeschlossen und ausgeschlossen werden sollen.

Im folgenden Beispiel wird verhindert, dass Benutzer in der free-access Rolle Lesevorgänge für Column3ausführen. Column3 Verweise auf in GET-Anforderungen (REST-Endpunkt) oder Abfragen (GraphQL Endpunkt) führen zu einer abgelehnten Anforderung:

    "book": {
      "source": "dbo.books",
      "permissions": [
        {
          "role": "free-access",
          "actions": [
            "create",
            "update",
            "delete",
            {
              "action": "read",
              "fields": {
                "include": [ "Column1", "Column2" ],
                "exclude": [ "Column3" ]
              }
            }
          ]
        }
      ]
    }

Hinweis

Um die Zugriffssteuerung für GraphQL Abfragen bei Verwendung des Daten-API-Generators mit Azure Cosmos DB zu erzwingen, müssen Sie die -Anweisung in der @authorize angegebenen GraphQL Schemadatei verwenden. Für GraphQL Mutationen und Filter in GraphQL Abfragen wird die Zugriffssteuerung jedoch weiterhin durch die Hier beschriebene Berechtigungskonfiguration erzwungen.

Sicherheit auf Elementebene

Datenbankrichtlinienausdrücke ermöglichen es, die Ergebnisse noch weiter einzuschränken. Datenbankrichtlinien übersetzen Ausdrücke in Abfrage-Prädikate, die für die Datenbank ausgeführt werden. Datenbankrichtlinienausdrücke werden für die folgenden Aktionen unterstützt:

  • create
  • Lesen
  • Update
  • Löschen

Warnung

Die Ausführungsaktion , die mit gespeicherten Prozeduren verwendet wird, unterstützt keine Datenbankrichtlinien.

Hinweis

Datenbankrichtlinien werden von CosmosDB for NoSQL derzeit nicht unterstützt.

Weitere Informationen zu Datenbankrichtlinien finden Sie in der Dokumentation zur Konfigurationsdatei .

Beispiel

Eine Datenbankrichtlinie, die die read Aktion für die consumer Rolle so einschränkt, dass nur Datensätze zurückgegeben werden, deren Titel "Beispieltitel" lautet.

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.title eq 'Sample Title'"
      }
    }
  ]
}

Verwandte Inhalte