Freigeben über

Autorisierung und Rollen im Daten-API-Generator

Der Daten-API-Generator verwendet einen rollenbasierten Autorisierungsworkflow. Jede eingehende Anforderung, authentifiziert oder nicht, wird einer Rolle zugewiesen. Rollen können Systemrollen oder Benutzerrollen sein. Die zugewiesene Rolle wird dann anhand der in der Konfiguration 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.

Abbildung, wie der Daten-API-Generator eine Rolle auswählt und Berechtigungen für eine Anforderung auswertet.

Bestimmen der Rolle des Benutzers

Keine Rolle verfügt über Standardberechtigungen. Sobald der Daten-API-Generator eine Rolle bestimmt, muss die Entität permissions für diese Rolle definieren actions , damit die Anforderung erfolgreich ist.

Die folgende Rollenauswertungsmatrix gilt für JWT-Beareranbieter (z. B. EntraID/AzureAD und Custom), bei denen der Client Authorization: Bearer <token> sendet.

Bearer Token bereitgestellt X-MS-API-ROLE bereitgestellt Angeforderte Rolle im Tokenanspruch roles enthalten Effektive Rolle /Ergebnis
Nein Nein N/A Anonymous
Ja (gültig) Nein N/A Authenticated
Ja (gültig) Ja Nein Abgelehnt (403 Verboten)
Ja (gültig) Ja Ja X-MS-API-ROLE-Wert
Ja (ungültig) Beliebig N/A Abgelehnt (401 Nicht autorisiert)

Um eine andere Rolle als Anonymous oder Authenticated zu verwenden, ist der X-MS-API-ROLE-Header erforderlich.

Hinweis

Eine Anforderung kann vielen Rollen im authentifizierten Subjekt zugeordnet werden. Der Daten-API-Generator wertet jedoch Berechtigungen und Richtlinien im Kontext genau einer effektiven Rolle aus. Wenn angegeben, wählt der X-MS-API-ROLE Header aus, welche Rolle verwendet wird.

Anbieterhinweise:

  • EasyAuth-Anbieter (z. B. AppService): Die Authentifizierung kann durch plattformseitig injizierte Header (z. B. X-MS-CLIENT-PRINCIPAL) anstelle eines Bearer-Tokens durchgeführt werden.
  • Simulator: Anforderungen werden für die Entwicklung und Tests als authentifiziert behandelt, ohne ein gültiges Token zu validieren.

Systemrollen

Systemrollen sind integrierte Rollen, die vom Daten-API-Generator erkannt werden. Eine Systemrolle wird automatisch einem Anforderer zugewiesen, unabhängig von der Rollenmitgliedschaft des Anforderers, die in ihren 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. Definierte Entitäten der Laufzeitkonfiguration müssen Berechtigungen für die Anonymous Rolle enthalten, wenn der nicht authentifizierte Zugriff erwünscht ist.

Beispiel

Die folgende Laufzeitkonfiguration des Daten-API-Generators veranschaulicht die explizite Konfiguration der Systemrolle Anonymous für den Lesezugriff auf die Book-Entität:

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

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

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 für den Lesezugriff auf die Book-Entität:

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

Benutzerrollen

Benutzerrollen sind Nichtsystemrollen, die Benutzern innerhalb des Identitätsanbieters zugewiesen sind, 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. Der authentifizierte Principal muss Ansprüche enthalten, die die Rollenmitgliedschaft eines Benutzers auflisten (z. B. der Anspruch im JWT roles).
  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

Das folgende Beispiel zeigt Anfragen an die Book-Entität, die in der Laufzeitkonfiguration des Data API Builders konfiguriert ist.

"Book": {
    "source": "books",
    "permissions": [
        {
      "role": "Anonymous",
            "actions": [ "read" ]
        },
        {
      "role": "Authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

Der Daten-API-Generator wertet Anforderungen im Kontext einer einzelnen effektiven Rolle aus. Wenn eine Anforderung authentifiziert wird und kein X-MS-API-ROLE Header angegeben wird, wertet der Daten-API-Generator die Anforderung standardmäßig im Kontext der Authenticated Systemrolle 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. Ein Beispiel für eine Anforderung, die ein Zugriffstoken und einen HTTP-Header beinhaltet:

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

Von Bedeutung

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

Erlaubnisse

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 Laufzeitkonfigurationsartikel beschrieben.

Von Bedeutung

Es kann 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 die Rolle enthalten ist, wird sie im X-MS-API-ROLE HTTP-Header festgelegt.

Standardmäßig sicher

Standardmäßig hat 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 darauf verwiesen wird.

Berechtigungen müssen explizit konfiguriert werden.

Um den nicht authentifizierten Zugriff auf eine Entität zuzulassen, muss die Anonymous Rolle explizit in den Berechtigungen der Entität definiert werden. Die Berechtigungen der book Entität werden beispielsweise explizit so festgelegt, dass nicht authentifizierter Lesezugriff zulässig ist:

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

Wenn Sie möchten, dass sowohl nicht authentifizierte als auch authentifizierte Benutzer Zugriff haben, erteilen Sie explizit Berechtigungen für beide Systemrollen (Anonymous und Authenticated).

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

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

Eine Entität erfordert keine Berechtigungen und ist nicht mit Berechtigungen für die Anonymous- und Authenticated-Rollen vorkonfiguriert. Innerhalb der Berechtigungskonfiguration einer Entität können eine oder mehrere Benutzerrollen definiert werden und alle anderen, nicht definierten Rollen, systemdefiniert oder benutzerdefiniert, wird der Zugriff automatisch 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 die book Entität zu verwenden:

"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 @authorize Direktive in Der bereitgestellten GraphQL-Schemadatei verwenden. Bei GraphQL-Mutationen und -Filtern in GraphQL-Abfragen erzwingt die Berechtigungskonfiguration jedoch weiterhin die Zugriffssteuerung wie zuvor beschrieben.

Aktionen

Aktionen beschreiben die Barrierefreiheit einer Entität im Bereich einer Rolle. Aktionen können einzeln oder mit der Wildcard-Abkürzung angegeben werden: * (Sternchen). Die Wildcard repräsentiert alle Aktionen, die für den Entitätstyp unterstützt werden.

  • Tabellen und Ansichten: create, read, updatedelete
  • Gespeicherte Prozeduren: execute

Weitere Informationen zu Aktionen finden Sie in der Konfigurationsdateidokumentation .

Feldzugriff

Sie können konfigurieren, auf welche Felder für eine Aktion zugegriffen werden soll. Sie können z. B. festlegen, welche Felder von der Aktion eingeschlossen und read werden sollen.

Im folgenden Beispiel wird verhindert, dass Benutzer in der Rolle free-access Lesevorgänge auf Column3 ausführen. Verweise auf Column3 in GET-Anforderungen (REST-Endpunkt) oder in 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 @authorize Direktive in Der bereitgestellten GraphQL-Schemadatei verwenden. Für GraphQL-Mutationen und -Filter in GraphQL-Abfragen erzwingt die Berechtigungskonfiguration jedoch weiterhin die Zugriffssteuerung, wie hier beschrieben.

Sicherheit auf Elementebene

Mithilfe von Datenbankrichtlinien können Sie Ergebnisse auf Zeilenebene filtern. Richtlinien werden in Abfrage-Prädikate übersetzt, die von der Datenbank ausgewertet werden, und stellen sicher, dass Benutzer nur auf autorisierte Datensätze zugreifen.

Unterstützte Aktionen Nicht unterstützt
read, updatedelete create, execute

Hinweis

Azure Cosmos DB für NoSQL unterstützt derzeit keine Datenbankrichtlinien.

Ausführliche Konfigurationsschritte, Syntaxreferenz und Beispiele finden Sie unter Konfigurieren von Datenbankrichtlinien.

Kurzes Beispiel
{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.ownerId eq @claims.userId"
      }
    }
  ]
}

Verwandte Inhalte

  • Last updated on