Partager via

Générer un jeton d’intégration

  • Article

S’APPLIQUE À : L’application possède des données L’utilisateur possède des données

Générer un jeton est une API REST qui permet de générer un jeton pour incorporer un rapport ou un modèle sémantique Power BI dans une application web ou un portail. Il est possible de générer un jeton pour un élément unique ou pour plusieurs rapports ou modèles sémantiques. Le jeton est utilisé pour autoriser votre demande sur le service Power BI.

L’API Générer un jeton utilise une identité unique (un utilisateur maître ou un principal du service) pour générer un jeton pour un utilisateur individuel, en fonction des informations d’identification de cet utilisateur dans l’application (identité effective).

Une fois l’authentification réussie, l’accès aux données pertinentes est accordé.

Remarque

Générer un jeton est l’API version 2 plus récente qui fonctionne à la fois pour les rapports et les modèles sémantiques, ainsi que pour les éléments uniques ou multiples. Cette version est préférable aux API version 1 héritées. Pour les tableaux de bord et les vignettes, utilisez GenerateTokenInGroup pour les tableaux de bord et GenerateTokenInGroup pour les vignettes V1.

Sécurisation de vos données

Si vous traitez des données provenant de plusieurs clients, il existe deux approches principales pour sécuriser vos données : Isolation basée sur l’espace de travail et Isolation basée sur la sécurité au niveau des lignes. Vous pouvez trouver une comparaison détaillée entre les deux dans Profils des principaux de services et sécurité au niveau des lignes.

Nous recommandons d’utiliser l’isolation basée sur l’espace de travail avec les profils, mais si vous souhaitez utiliser l’approche RLS, consultez la Section RLS à la fin de cet article.

Sécurité et autorisations des jetons

Dans les API Générer un jeton, la section GenerateTokenRequest décrit les autorisations de jeton.

Niveau d’accès

  • Utilisez le paramètre allowEdit pour accorder à l’utilisateur des autorisations d’affichage ou de modification.

  • Ajoutez l’ID d’espace de travail au jeton intégré pour permettre à l’utilisateur de créer de nouveaux rapports (SaveAs ou CreateNew) dans cet espace de travail.

Sécurité au niveau des lignes

Avec la Sécurité au niveau de la ligne (RLS), l’identité que vous utilisez peut être différente de l’identité du principal de service ou de l’utilisateur principal que vous utilisez pour générer le jeton. En utilisant différentes identités, vous pouvez afficher des informations incorporées en fonction de l’utilisateur que vous ciblez. Par exemple, dans votre application, vous pouvez demander aux utilisateurs de se connecter, puis afficher un rapport contenant uniquement des informations sur les ventes si l’utilisateur connecté est un employé du service commercial.

Si vous utilisez la sécurité au niveau des lignes, vous pouvez, dans certains cas, ignorer l’identité de l’utilisateur (le paramètre EffectiveIdentity). Quand vous n’utilisez pas le paramètre EffectiveIdentity, le jeton a accès à l’ensemble de la base de données. Cette méthode peut être utilisée pour accorder l’accès aux utilisateurs, comme les administrateurs et les responsables, qui disposent des autorisations nécessaires pour afficher l’ensemble du modèle sémantique. Toutefois, vous ne pouvez pas utiliser cette méthode dans tous les scénarios. Le tableau ci-dessous répertorie les différents types de RLS et indique la méthode d’authentification qui peut être utilisée sans spécifier l’identité d’un utilisateur.

Le tableau indique également les considérations et limitations applicables à chaque type de RLS.

Type de RLS Puis-je générer un jeton d’incorporation sans spécifier d’ID d’utilisateur effectif ? Observations et limitations
Sécurité au niveau des lignes cloud (RLS cloud) ✔ Utilisateur maître
✖ Principal de service
RDL (rapports paginés) ✖ Utilisateur maître
✔ Principal de service		 Vous ne pouvez pas utiliser un utilisateur maître pour générer un jeton d’incorporation pour RDL.
Analysis Services (AS) sur une connexion active locale ✔ Utilisateur maître
✖ Principal de service		 L’utilisateur qui génère le jeton incorporé a également besoin de l’une des autorisations suivantes :
  • Autorisations d’administrateur de passerelle
  • Autorisation d’emprunt d’identité de source de données (ReadOverrideEffectiveIdentity)
    		•
    Connexion active Azure Analysis Services (AS) ✔ Utilisateur maître
    ✖ Principal de service    		 L’identité de l’utilisateur qui génère le jeton incorporé ne peut pas être substituée. Les données personnalisées peuvent être utilisées pour implémenter une sécurité RLS dynamique ou un filtrage sécurisé.

    Remarque : Le principal du service doit fournir son ID d’objet en tant qu’identité effective (nom d'utilisateur RLS).
    Authentification unique ✔ Utilisateur maître
    ✖ Principal de service    		 Une identité explicite (SSO) peut être fournie à l’aide de la propriété d’objet Blob d’identité dans un objet d’identité effective
    Authentification unique et RLS cloud ✔ Utilisateur maître
    ✖ Principal de service    		 Vous devez fournir les éléments suivants :
  • Identité explicite (SSO) dans la propriété d’objet Blob d’identité dans un objet d’identité effective
  • Identité effective (RLS) (nom d’utilisateur)
    		•

    Notes

    Les principaux de service doivent toujours fournir les informations suivantes :

    • Identité de n’importe quel élément avec un modèle sémantique SNL.
    • Pour un modèle sémantique avec authentification unique (SSO), une identité SNL effective avec l’identité contextuelle (SSO) définie.

    DirectQuery pour les modèles sémantiques Power BI

    Pour incorporer un rapport Power BI qui a un modèle sémantique avec une connexion Direct Query à un autre modèle sémantique Power BI, procédez comme suit :

    Renouveler les jetons avant leur expiration

    Les jetons ont une limite de temps. Cela signifie que vous disposez d’un temps limité pour interagir avec un élément Power BI après l’avoir incorporé. Pour offrir une expérience continue à vos utilisateurs, renouvelez (ou actualisez) le jeton avant son expiration.

    Tableaux de bord et vignettes

    Le jeton Generate fonctionne pour les rapports et les modèles sémantiques. Pour générer un jeton intégré pour un tableau de bord ou une vignette, utilisez les API version 1 GenerateTokenInGroup pour les tableaux de bord ou GenerateTokenInGroup pour les vignettes. Ces API génèrent des jetons pour un seul élément à la fois. Vous ne pouvez pas générer de jeton pour plusieurs éléments.

    Pour ces API :

    • Utilisez le paramètre accessLevel pour déterminer le niveau d’accès de l’utilisateur.

      • Affichage : accordez à l’utilisateur les autorisations d’affichage.

      • Modification : accordez à l’utilisateur les autorisations d’affichage et de modification (s’applique uniquement lors de la génération d’un jeton incorporé pour un rapport).

      • Création : autorisez les utilisateurs à créer un rapport (s’applique uniquement lors de la génération d’un jeton intégré pour la création d’un rapport). Pour la création de rapports, vous devez également fournir le paramètre datasetId.

    • Utilisez le booléen allowSaveAs pour permettre aux utilisateurs d’enregistrer le rapport en tant que nouveau rapport. Ce paramètre est défini sur faux par défaut et s’applique uniquement lors de la génération d’un jeton intégré pour un rapport.

    Observations et limitations

    • Pour des raisons de sécurité, la durée de vie du jeton intégré est fixée à la durée de vie restante du jeton Microsoft Entra utilisé pour appeler l’API GenerateToken. Par conséquent, si vous utilisez le même jeton Microsoft Entra pour générer plusieurs jetons intégrés, la durée de vie des jetons intégrés générés sera plus courte à chaque appel.

    • Si le modèle sémantique et l’élément à intégrer se trouvent dans deux espaces de travail différents, le principal de service ou l’utilisateur principal doit être au moins membre des deux espaces de travail.

    • Vous ne pouvez pas créer de jeton incorporé pour Mon espace de travail.

    Contenu connexe