Autorisation et rôles dans le générateur d’API de données

Le générateur d’API de données utilise un flux de travail d’autorisation en fonction du rôle. Toute demande entrante, authentifiée ou non, est affectée à un rôle. Les rôles peuvent être des rôles système ou des rôles d’utilisateur. Le rôle affecté est ensuite vérifié par rapport aux autorisations définies spécifiées dans la configuration pour comprendre quelles actions, champs et stratégies sont disponibles pour ce rôle sur l’entité demandée.

Détermination du rôle de l’utilisateur

Aucun rôle n’a d’autorisations par défaut. Une fois que le générateur d’API de données détermine un rôle, l’entité permissions doit définir actions ce rôle pour que la demande réussisse.

La matrice d’évaluation de rôle suivante s’applique aux fournisseurs de porteur JWT (par exemple, EntraID/AzureAD et Custom) où le client envoie Authorization: Bearer <token>.

Jeton d'authentification du porteur fourni	X-MS-API-ROLE Fourni	Rôle demandé présent dans la revendication de jeton roles	Rôle / résultat effectif
Non	Non	N/A	Anonymous
Oui (valide)	Non	N/A	Authenticated
Oui (valide)	Oui	Non	Rejeté (403 Interdit)
Oui (valide)	Oui	Oui	valeur X-MS-API-ROLE
Oui (non valide)	N'importe lequel	N/A	Rejeté (401 Non autorisé)

Pour utiliser un rôle autre que Anonymous ou Authenticated, l’en-tête X-MS-API-ROLE est requis.

Remarque

Une demande peut être associée à de nombreux rôles dans l'entité authentifiée. Toutefois, le générateur d’API de données évalue les autorisations et les stratégies dans le contexte d’un rôle efficace. Lorsqu’il est fourni, l’en-tête X-MS-API-ROLE sélectionne le rôle utilisé.

Notes du fournisseur :

• Fournisseurs EasyAuth (par exemple AppService) : l’authentification peut être établie par des en-têtes injectés par plateforme (comme X-MS-CLIENT-PRINCIPAL) plutôt que par un jeton porteur.
• Simulator: les requêtes sont traitées comme authentifiées pour le développement/test, sans valider un jeton réel.

Rôles système

Les rôles système sont des rôles intégrés reconnus par le générateur d’API de données. Un rôle système est attribué automatiquement à un demandeur, quel que soit l’appartenance au rôle du demandeur indiquée dans ses jetons d’accès. Il existe deux rôles système : Anonymous et Authenticated.

Rôle système anonyme

Le Anonymous rôle système est affecté aux requêtes exécutées par des utilisateurs non authentifiés. Les entités définies par la configuration du runtime doivent inclure des autorisations pour le Anonymous rôle si l’accès non authentifié est souhaité.

Exemple :

La configuration du runtime du générateur d’API de données suivante illustre explicitement la configuration du rôle Anonymous système pour inclure l’accès en lecture à l’entité Book :

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

Lorsqu’une application cliente envoie une demande d’accès à l’entité Book pour le compte d’un utilisateur non authentifié, l’application ne doit pas inclure l’en-tête Authorization HTTP.

Rôle système authentifié

Le Authenticated rôle système est attribué aux requêtes exécutées par les utilisateurs authentifiés.

Exemple :

La configuration du runtime du générateur d’API de données suivante illustre explicitement la configuration du rôle Authenticated système pour inclure l’accès en lecture à l’entité Book :

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

Rôles d'utilisateur

Les rôles d’utilisateur ne sont pas des rôles de système qui sont attribués aux utilisateurs au sein du fournisseur d’identité que vous avez défini dans la configuration du runtime. Pour que le générateur d’API de données évalue une demande dans le contexte d’un rôle d’utilisateur, deux exigences doivent être remplies :

1. Le principal authentifié doit inclure des revendications de rôle qui répertorient l’appartenance au rôle d’un utilisateur (par exemple, la revendication JWT roles ).
2. L’application cliente doit inclure l’en-tête X-MS-API-ROLE HTTP avec des requêtes et définir la valeur de l’en-tête comme rôle d’utilisateur souhaité.

Exemple d’évaluation de rôle

L’exemple suivant illustre les demandes adressées à l’entité Book configurée dans la configuration du runtime du générateur d’API de données comme suit :

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

Le générateur d’API de données évalue les requêtes dans le contexte d’un rôle efficace unique. Si une demande est authentifiée et qu’aucun en-tête X-MS-API-ROLE n’est fourni, le générateur d’API de données évalue la demande dans le contexte du rôle système Authenticated par défaut.

Si la requête de l’application cliente inclut également l’en-tête X-MS-API-ROLE HTTP avec la valeur author, la requête est évaluée dans le contexte du author rôle. Exemple de requête incluant un jeton d’accès et X-MS-API-ROLE un en-tête HTTP :

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

Important

La demande d’une application cliente est rejetée lorsque la revendication du roles jeton d’accès fourni ne contient pas le rôle répertorié dans l’en-tête X-MS-API-ROLE .

Autorisations

Les autorisations décrivent :

• Qui peut effectuer des demandes sur une entité en fonction de l’appartenance au rôle ?
• Quelles actions (créer, lire, mettre à jour, supprimer, exécuter) qu’un utilisateur peut effectuer ?
• Quels champs sont accessibles pour une action particulière ?
• Quelles restrictions supplémentaires existent sur les résultats retournés par une requête ?

La syntaxe de définition des autorisations est décrite dans l’article de configuration du runtime.

Important

Plusieurs rôles peuvent être définis dans la configuration des autorisations d’une entité unique. Toutefois, une requête est évaluée uniquement dans le contexte d’un seul rôle :

• Par défaut, le rôle système Anonymous ou Authenticated
• Lorsqu'il est inclus, le rôle est défini dans l'en-tête HTTP X-MS-API-ROLE.

Sécurisé par défaut

Par défaut, une entité n’a pas d’autorisations configurées, ce qui signifie que personne ne peut accéder à l’entité. En outre, le générateur d’API de données ignore les objets de base de données lorsqu’ils ne sont pas référencés dans la configuration du runtime.

Les autorisations doivent être configurées explicitement

Pour autoriser l’accès non authentifié à une entité, le Anonymous rôle doit être défini explicitement dans les autorisations de l’entité. Par exemple, les autorisations de l’entité book sont explicitement définies pour autoriser l’accès en lecture non authentifié :

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

Si vous souhaitez que les utilisateurs non authentifiés et authentifiés aient accès, accordez explicitement des autorisations aux rôles système (Anonymous et Authenticated).

Lorsque les opérations de lecture doivent être limitées aux utilisateurs authentifiés uniquement, la configuration des autorisations suivante doit être définie, ce qui entraîne le rejet des demandes non authentifiées :

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

Une entité ne nécessite pas d'autorisations et n'est pas préconfigurée avec celles-ci pour les rôles Anonymous et Authenticated. Un ou plusieurs rôles d’utilisateur peuvent être définis dans la configuration des autorisations d’une entité et tous les autres rôles, systèmes ou utilisateurs non définis sont automatiquement refusés.

Dans l’exemple suivant, le rôle administrator d’utilisateur est le seul rôle défini pour l’entité book . Un utilisateur doit être membre du administrator rôle et inclure ce rôle dans l’en-tête X-MS-API-ROLE HTTP pour fonctionner sur l’entité book :

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

Remarque

Pour appliquer le contrôle d’accès pour les requêtes GraphQL lors de l’utilisation du générateur d’API de données avec Azure Cosmos DB, vous devez utiliser la @authorize directive dans votre fichier de schéma GraphQL fourni. Toutefois, pour les mutations et les filtres GraphQL dans les requêtes GraphQL, la configuration des autorisations applique toujours le contrôle d’accès comme décrit précédemment.

Actions

Les actions décrivent l’accessibilité d’une entité dans l’étendue d’un rôle. Les actions peuvent être spécifiées individuellement ou avec le raccourci générique : * (astérisque). Le raccourci générique représente toutes les actions prises en charge pour le type d’entité :

• Tables et vues : create, read, update, delete
• Procédures stockées : execute

Pour plus d’informations sur les actions, consultez la documentation du fichier de configuration .

Accès aux champs

Vous pouvez configurer les champs qui doivent être accessibles pour une action. Par exemple, vous pouvez définir les champs à inclure et exclure de l’action read .

L’exemple suivant empêche les utilisateurs du free-access rôle d’effectuer des opérations de lecture sur Column3. Les références à Column3 dans les requêtes GET (point de terminaison REST) ou les requêtes GraphQL (point de terminaison GraphQL) entraînent le rejet de la requête :

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

Remarque

Pour appliquer le contrôle d’accès pour les requêtes GraphQL lors de l’utilisation du générateur d’API de données avec Azure Cosmos DB, vous devez utiliser la @authorize directive dans votre fichier de schéma GraphQL fourni. Toutefois, pour les mutations et les filtres GraphQL dans les requêtes GraphQL, la configuration des autorisations applique toujours le contrôle d’accès, comme décrit ici.

Sécurité au niveau de l’élément

Les stratégies de base de données vous permettent de filtrer les résultats au niveau de la ligne. Les stratégies se traduisent par des prédicats de requête que la base de données évalue, ce qui garantit aux utilisateurs d’accéder uniquement aux enregistrements autorisés.

Actions prises en charge	Non prise en charge
read, updatedelete	create, execute

Remarque

Azure Cosmos DB pour NoSQL ne prend actuellement pas en charge les stratégies de base de données.

Pour obtenir des étapes de configuration détaillées, des informations de référence sur la syntaxe et des exemples, consultez Configurer des stratégies de base de données.

Exemple rapide

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

Contenu connexe

• Configurer des stratégies de base de données pour le filtrage au niveau des lignes
• Configurer l’authentification d’ID Microsoft Entra
• Configurer l’authentification du simulateur pour les tests locaux