Permissions des API
En tant que développeur d’API, vous devez :
Déterminer les informations auxquelles vous souhaitez que les applications puissent accéder au nom d’un utilisateur.
Définir ces niveaux d’accès en tant que champs d’application personnalisés. (Pour savoir ce que sont les permissions, lisez Permissions.)
Identifier ces permissions pour que les applications appelantes puissent les utiliser.
Façons d’utiliser permissions des API
Vous pouvez utiliser les permissions des API de différentes manières :
Dans le cas d’une API où l’application appelante est une application tierce ou externe, c’est cette dernière qui demandera à l’utilisateur l’autorisation d’accéder aux permissions demandées. L’utilisateur pourra ensuite accepter ou refuser la demande
Dans le cas où l’application appelante est une application de première partie ou une application enregistrée sous le même domaine Auth0 que l’API qu’elle appelle, le consentement de l’utilisateur n’est pas demandé par défaut. Cependant, vous pouvez le configurer pour qu’il soit exigé.
Dans une API où l’application appelante est un service d’arrière-plan, qu’il s’agisse d’une tierce partie ou d’une première partie, et où il n’y a pas d’utilisateur, le consentement de l’utilisateur n’est jamais demandé.
Tous ces exemples utilisent des permissions pour limiter l’accès au moyen d’un jeton. Si vous le souhaitez, votre API peut également utiliser une logique additionnelle au-delà du jeton pour appliquer un contrôle d’accès plus étendu.
Pour un exemple montrant comment demander un accès personnalisé à l’API pour votre application, consultez Exemples de cas d’utilisation : Permissions et demandes.
Exemple : Une API appelée par une application tierce
Supposons que vous développiez une API qui permette à des applications de paiement en ligne de connaître l’état des comptes bancaires. Ces dernières peuvent avoir besoin de vérifier le solde du compte ou d’effectuer un transfert. Pour ce faire, vous devez créer deux permissions pour votre API : l’une pour lire le solde d’un compte (1read:balance 1) et l’autre pour effectuer des virements (2transfer:funds 2). Votre API est enregistrée auprès d’Auth0.
Une application appelante demandera à l’utilisateur l’autorisation d’accéder aux permissions demandés, et l’utilisateur approuvera ou refusera la demande. L’application peut demander un accès en lecture au solde de l’utilisateur en incluant la permission read:balance dans sa demande, un accès pour effectuer des transferts de fonds en incluant la permission transfer:funds dans sa demande, ou un accès pour lire le solde de l’utilisateur et transférer des fonds en incluant à la fois les permissions read:balance et transfer:funds dans sa demande.
Désormais, lorsque l’application appellera votre API, elle inclura un jeton qui vérifiera que l’utilisateur a fourni l’autorisation d’accéder à son contenu et indiquera également les permissions que l’utilisateur a approuvés. Votre API doit respecter les permissions approuvées et ne communiquer à l’application appelante que les informations autorisées par l’utilisateur.
Exemple : Une API appelée par une application première partie
Supposons que vous construisiez une API qui fournit des données à une application événementielle, que vous avez également programmée. Vous mettez en œuvre le contrôle d’accès basé sur les rôles (RBAC), en créant un rôle organizer (organisateur) et un rôle participant. Les utilisateurs ayant le rôle 'organizer (organisateur) doivent créer et mettre à jour des événements, tandis que les utilisateurs ayant le rôle participant doivent visualiser les événements et s’y inscrire. Pour cela, vous créez quatre permissions pour votre API : une qui autorise l’accès à la création d’événements (create:events), une qui autorise l’accès à la mise à jour d’événements (update:events), une qui autorise l’accès à la lecture seule d’événements (view:events) et une qui autorise l’accès à l’enregistrement d’événements (register:events). Votre API et votre application d’événement sont toutes deux enregistrées auprès d’Auth0, et l’option Allow Skipping User Consent (Autoriser l’omission de l’étape du consentement de l’utilisateur) pour les applications de première partie est activée pour votre API. Vous avez installé Authorization Extension, configuré un rôle organizer (organisateur), créé les permissions create:events et update:events, et les avez attribuées à l’utilisateur A. Vous avez également configuré un rôle participant, créé les permissions view:events et register:events, et les avez attribuées à l’utilisateur B.
L’utilisateur A s’authentifie auprès de l’application appelante, qui demande les permissions nécessaires, mais comme il s’agit d’une application de première partie, le consentement de l’utilisateur n’est pas demandé. L’application peut demander n’importe quelle combinaison des permissions create:events, update:events, view:events et register:events, mais l’utilisateur A est reconnu comme ayant le rôle d’organisateur et ne se voit donc accorder que les permissions create:events et update:events.
Désormais, lorsque l’application appellera votre API, elle inclura un jeton qui vérifiera qu’elle a l’autorisation d’accéder uniquement aux permissions associées au rôle de l’utilisateur authentifié.
Exemple : Une API appelée par un service back-end
Supposons que vous travaillez pour un hôpital et que vous disposez d’une API qui produit de grandes quantités de données d’imagerie chaque fois qu’un patient passe une IRM. Vous stockez les données d’imagerie localement pendant six mois, mais l’hôpital a besoin que les images soient stockées à long terme pour des raisons de conformité réglementaire. Pour cette raison, l’hôpital dispose d’un service qui copie chaque nuit les données d’imagerie vers une solution de stockage à froid hors site et qui supprime toutes les données médicales locales après six mois de stockage.
Pour cela, vous créez deux permissions pour votre API : une qui autorise l’accès en lecture à vos données d’imagerie (read:images) et une qui autorise l’accès en suppression à vos données d’imagerie (delete:images). Votre API et votre service automatisé sont enregistrés auprès d’Auth0, et vous avez autorisé le service automatisé à demander des jetons pour votre API.
Le service automatisé appelant demandera les permissions nécessaires, mais comme il n’y a pas d’utilisateur, le consentement ne sera pas demandé. Le service peut demander un accès en lecture à vos données d’imagerie en incluant la permission read:images dans sa demande, un accès en suppression en incluant la permission delete:images dans sa demande, ou un accès à la fois en lecture et en suppression en incluant les permissions read:images et delete:images dans sa demande.
Désormais, lorsque le service automatisé appellera votre API, il inclura un jeton qui vérifiera qu’il dispose de l’autorisation pour les permissions demandées.
Limiter les permissions des API
Une application peut inclure dans sa demande n’importe quelle permission définie pour une API. Cependant, au lieu d’autoriser la demande de toutes les permissions disponibles, vous pouvez limiter les permissions pour certains utilisateurs. Par exemple, un utilisateur de votre application peut se voir attribuer un rôle de sorte que les requêtes effectuées en son nom soient limitées aux permissions attribuées à ce rôle. Pour cela, vous pouvez utiliser Authorization Extension et créer une règle personnalisée. Pour en savoir plus sur les règles, consultez Règles d'Auth0.
Pour en savoir plus sur cette approche, lisez notre Scénario d’architecture SPA+API. En particulier, vous pouvez consulter la section Configurer l’extension d’autorisation pour apprendre à configurer l’extension d’autorisation et à créer une règle personnalisée qui garantira que les permissions sont accordées en fonction du rôle de l’utilisateur.