Partager via

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

  • Article

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

Rôles

Les rôles définissent le contexte d’autorisations dans lequel une demande doit être exécutée. Pour chaque entité définie dans la configuration du runtime, vous pouvez définir un ensemble de rôles et d’autorisations associées qui déterminent comment l’entité est accessible dans les points de terminaison REST et GraphQL.

Le Générateur d’API de données évalue les requêtes dans le contexte d’un rôle unique :

  • anonymous lorsqu’aucun jeton d’accès n’est présenté.
  • authenticated lorsqu’un jeton d’accès valide est présenté.
  • <CUSTOM_USER_ROLE> lorsqu’un jeton d’accès valide est présenté et que l’en-tête X-MS-API-ROLE HTTP est inclus en spécifiant un rôle d’utilisateur qui est également inclus dans la revendication du roles jeton d’accès.

Les rôles ne sont pas additifs, ce qui signifie qu’un utilisateur qui est membre des deux Role1 rôles et Role2 n’hérite pas des autorisations associées aux deux rôles.

Rôles de 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, quelle 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 attribué 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 d’exécution du générateur d’API de données suivante montre 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 requête accédant à 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 des utilisateurs authentifiés.

Exemple

La configuration d’exécution du générateur d’API de données suivante montre 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 sont des rôles non 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 requête dans le contexte d’un rôle d’utilisateur, deux conditions doivent être remplies :

  1. Le jeton d’accès fourni par l’application cliente doit inclure des revendications de rôle qui répertorient l’appartenance au rôle d’un utilisateur.
  2. L’application cliente doit inclure l’en-tête X-MS-API-ROLE HTTP avec les 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" ]
        }
    ]
}

Dans Static Web Apps, un utilisateur est membre du rôle anonyme par défaut. Si l’utilisateur est authentifié, l’utilisateur est membre des anonymous rôles et authenticated .

Lorsqu’une application cliente envoie une requête authentifiée au générateur d’API de données déployé à l’aide de Static Web Apps connexions aux bases de données (préversion), l’application cliente fournit un jeton d’accès qui Static Web Apps se transforme en JSON :

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

Étant donné que le Générateur d’API de données évalue les requêtes dans le contexte d’un rôle unique, il évalue la requête dans le contexte du rôle authenticated système 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 demande 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 -r 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 sont les 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 configuration du runtime.

Important

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

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

Sécurisé par défaut

Par défaut, une entité n’a aucune autorisation configurée, 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" ]
  }]
}

Pour simplifier la définition des autorisations sur une entité, supposons que s’il n’existe pas d’autorisations spécifiques pour le authenticated rôle, les autorisations définies pour le anonymous rôle sont utilisées. La book configuration indiquée précédemment permet à n’importe quel utilisateur anonyme ou authentifié d’effectuer des opérations de lecture sur l’entité book .

Lorsque les opérations de lecture doivent être limitées aux utilisateurs authentifiés uniquement, la configuration d’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é n’exige pas et n’est pas préconfigurée avec des autorisations pour les anonymous rôles 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 non définis, système ou utilisateur, se voient automatiquement refuser l’accè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": [ "*" ]
  }]
}

Notes

Pour appliquer le contrôle d’accès aux requêtes GraphQL lors de l’utilisation du générateur d’API de données avec Azure Cosmos DB, vous devez utiliser la directive dans le @authorizefichier de schéma GraphQL fourni. Toutefois, pour les mutations GraphQL et les filtres dans les requêtes GraphQL, le contrôle d’accès est toujours appliqué par la configuration des autorisations 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 au champ

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 rôle d’effectuer free-access 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) entraînent un rejet de requête :

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

Notes

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

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

Les expressions de stratégie de base de données permettent de restreindre encore davantage les résultats. Les stratégies de base de données traduisent les expressions en prédicats de requête exécutés sur la base de données. Les expressions de stratégie de base de données sont prises en charge pour les actions suivantes :

  • create
  • lire
  • update
  • supprimer

Avertissement

L’action d’exécution , utilisée avec les procédures stockées, ne prend pas en charge les stratégies de base de données.

Notes

Les stratégies de base de données ne sont actuellement pas prises en charge par CosmosDB pour NoSQL.

Pour plus d’informations sur les stratégies de base de données, consultez la documentation du fichier de configuration .

Exemple

Stratégie de base de données limitant l’action read sur le consumer rôle pour renvoyer uniquement les enregistrements dont le titre est « Exemple de titre ».

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

Contenu connexe