Share via

Authentification et autorisation pour l’API Insights Azure Time Series

  • Article

Remarque

Le service Time Series Insights (TSI) ne sera plus pris en charge après le mois de mars 2025. Pensez à migrer dès que possible les environnements TSI existants vers d’autres solutions. Pour plus d’informations sur la dépréciation et la migration, consultez notre documentation.

Selon les besoins de votre entreprise, votre solution peut inclure une ou plusieurs applications clientes que vous utilisez pour interagir avec les API de votre environnement Azure Time Series Insights. Azure Time Series Recommandations effectue l’authentification à l’aide des jetons de sécurité Microsoft Entra basés sur OAUTH 2.0. Pour authentifier vos clients, vous devez obtenir un jeton du porteur avec les autorisations appropriées et le transmettre avec vos appels d’API. Ce document décrit plusieurs méthodes pour obtenir des informations d’identification que vous pouvez utiliser pour obtenir un jeton du porteur et s’authentifier, notamment à l’aide de l’identité managée et de l’inscription d’application Microsoft Entra.

Identités managées

Les sections suivantes décrivent comment utiliser une identité managée à partir de Microsoft Entra ID pour accéder à l’API Azure Time Series Recommandations. Sur Azure, les identités managées évitent aux développeurs d’avoir à gérer les informations d’identification en fournissant une identité pour la ressource Azure dans Microsoft Entra ID et en l’utilisant pour obtenir des jetons Microsoft Entra. Voici quelques-uns des avantages de l’utilisation des identités managées :

  • Vous n’avez pas besoin de gérer les informations d’identification. Vous n’avez même pas accès à ces dernières.
  • Vous pouvez utiliser des identités managées pour vous authentifier auprès de n’importe quel service Azure prenant en charge l’authentification Microsoft Entra, y compris Azure Key Vault.
  • Les identités managées peuvent être utilisées sans coût supplémentaire.

Pour en savoir plus sur les deux types d’identités managées, consultez Que sont les identités managées pour les ressources Azure ?

Vous pouvez utiliser des identités gérées à partir de vos :

  • Machines virtuelles Azure
  • Azure App Services
  • Azure Functions
  • Instances de conteneur Azure
  • Et bien plus...

Pour la liste complète, consultez Services Azure qui prennent en charge les identités gérées pour les ressources Azure.

Inscription d’applications auprès de Microsoft Entra

Nous vous recommandons d’utiliser des identités managées autant que possible afin de ne pas avoir à gérer les informations d’identification. Si votre application cliente n’est pas hébergée sur un service Azure qui prend en charge les identités managées, vous pouvez inscrire votre application auprès d’un locataire Microsoft Entra. Lorsque vous inscrivez votre application avec l’ID Microsoft Entra, vous créez une configuration d’identité pour votre application qui lui permet de s’intégrer à l’ID Microsoft Entra. Quand vous inscrivez une application dans le portail Azure, vous choisissez s’il s’agit d’une application monolocataire (accessible uniquement dans votre locataire) ou multilocataire (accessible dans d’autres locataires). De plus, vous pouvez éventuellement définir un URI de redirection (auquel le jeton d’accès est envoyé).

Une fois l’inscription de l’application terminée, vous disposez d’une instance globale unique de l’application (objet application) qui réside dans votre locataire ou annuaire de base. Vous disposez également d’un ID global unique pour votre application (l’ID de l’application ou du client). Dans le portail, vous pouvez ensuite ajouter des secrets ou des certificats, ainsi que des étendues pour que votre application fonctionne, personnaliser votre application dans la boîte de dialogue de connexion, et bien plus.

Si vous inscrivez une application dans le portail, un objet application et un objet principal de service sont automatiquement créés dans votre locataire de base. Si vous inscrivez/créez une application à l’aide des API Microsoft Graph, la création de l’objet principal de service est une étape distincte. Un objet principal de service est requis pour demander des jetons.

Veillez à consulter la liste de vérification Sécurité pour votre application. En guise de meilleure pratique, il est recommandé d’utiliser des informations d’identification de certificat, pas des informations d’identification de mot de passe (clés secrètes client).

Pour plus d’informations, consultez les objets d’application et de principal de service dans Microsoft Entra ID .

Étape 1 : créer votre identité managée ou inscription d’application

Une fois que vous avez déterminé si vous allez utiliser une identité managée ou une inscription d’application, l’étape suivante consiste à en approvisionner une.

Identité gérée

Les étapes à suivre pour créer une identité managée varient en fonction de l’emplacement de votre code et de la création ou non d’une identité attribuée par le système ou par l’utilisateur. Pour comprendre la différence, consultez Types d’identités managées. Une fois que vous avez sélectionné votre type d’identité, recherchez et suivez le tutoriel approprié dans la documentation sur les identités managées Microsoft Entra. Vous y trouverez des instructions sur la configuration des identités managées pour :

Inscription de l’application

Suivez les étapes décrites dans Inscrire une application.

  • Après avoir sélectionné la plateforme appropriée à l’étape 4 de la section Configurer les paramètres de la plateforme, configurez vos URI de redirection et Jetons d’accès dans le volet latéral situé à droite de l’interface utilisateur.

    • L’URI de redirection doit correspondre à l’adresse fournie par la requête d’authentification :

      • Pour les applications hébergées dans un environnement de développement local, sélectionnez Client public (mobile et bureau). Veillez à affecter la valeur Oui à Client public.
      • Pour les applications monopages hébergées sur Azure App Service, sélectionnez Web.

    • Déterminez si une URL de déconnexion est appropriée.

    • Activez le flux d’octroi implicite en cochant les Jeton d'accès ou Jetons d'ID.

    Create Redirect URIs

    Cliquez sur Configurer, puis sur Enregistrer.

  • Associez votre application Microsoft Entra Azure Time Series Recommandations. Sélectionnez Autorisations de l’API>Ajouter une autorisation>API que mon organisation utilise.

    Associate an API with your Microsoft Entra app

    Saisissez Azure Time Series Insights dans la barre de recherche, puis sélectionnez Azure Time Series Insights.

  • Ensuite, spécifiez le genre d’autorisation d’API exigé par votre application. Par défaut, Autorisations déléguées est en surbrillance. Choisissez un type d’autorisation puis, sélectionnez Ajouter les autorisations.

    Specify the kind of API permission your app requires

  • Ajoutez des informations d’identification si l’application doit appeler les API de votre environnement elle-même. Les informations d’identification permettent à votre application de s’authentifier de façon autonome, sans qu’aucune interaction utilisateur ne soit nécessaire au moment de l’exécution.

Étape 2 : accorder l’accès

Lorsque votre environnement Azure Time Series Insights reçoit une demande, le jeton du porteur de l’appelant est d’abord validé. Si la validation réussit, l’appelant a été authentifié. Ensuite, une autre vérification est effectuée pour s’assurer que l’appelant est autorisé à effectuer l’action demandée. Pour autoriser un utilisateur ou un principal de service, vous devez commencer par lui accorder un accès à l’environnement en lui attribuant le rôle Lecteur ou Contributeur.

  • Pour accorder l’accès via l’interface utilisateur du portail Azure, suivez les instructions fournies dans l’article Accorder l’accès aux données dans un environnement . Lors de la sélection de l’utilisateur, vous pouvez rechercher l’identité managée ou l’inscription d’application par son nom ou par son ID.

  • Pour accorder l’accès à l’aide d’Azure CLI, exécutez la commande suivante. Pour obtenir la liste complète des commandes disponibles pour gérer l’accès, consultez la documentation ici.

    az tsi access-policy create --name "ap1" --environment-name "env1" --description "some description" --principal-object-id "aGuid" --roles Reader Contributor --resource-group "rg1"

Remarque

L’extension timeseriesinsights pour Azure CLI nécessite la version 2.11.0 ou une version ultérieure. L’extension est automatiquement installée la première fois que vous exécutez une commande az tsi access-policy. En savoir plus sur les extensions.

Étape 3 : demande de jetons

Une fois que votre identité managée ou votre inscription d’application ont été approvisionnées et qu’un rôle leur a été attribué, vous êtes prêt à commencer à les utiliser pour demander des jetons du porteur OAuth 2.0. La méthode que vous utilisez pour obtenir un jeton varie selon l’emplacement d’hébergement de votre code et le langage de votre choix. Lorsque vous spécifiez la ressource (également appelée « audience » du jeton), vous pouvez identifier Azure Time Series Insights par son URL ou son GUID :

  • https://api.timeseries.azure.com/
  • 120d688d-1518-4cf7-bd38-182f158850b6

Important

Si vous utilisez l’URL en tant qu’ID de ressource, le jeton doit être émis exactement à https://api.timeseries.azure.com/. La barre oblique de fin est requise.

  • Si vous utilisez Postman, votre AuthURL sera donc : https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default
  • https://api.timeseries.azure.com/ est valide, mais https://api.timeseries.azure.com ne l’est pas.

Identités managées

Lors de l’accès à partir de Azure App Service ou de Functions, suivez les instructions fournies dans Obtenir des jetons pour les ressources Azure.

Pour les fonctions et applications .NET, la façon la plus simple d’utiliser une identité managée consiste à recourir à la Bibliothèque de client Azure Identity pour .NET. Cette bibliothèque client est populaire en raison de sa simplicité et de ses avantages en matière de sécurité. Les développeurs peuvent écrire du code une seule fois et laisser la bibliothèque de client déterminer comment s’authentifier en fonction de l’environnement d’application, selon qu’il s’agit d’une station de travail de développeur utilisant un compte de développeur ou déployée dans Azure à l’aide d’une identité de service managée. Pour obtenir des conseils sur la migration à partir de la bibliothèque AppAuthentication prédécesseur, lisez Guide de migration AppAuthentication vers Azure.Identity.

Demandez un jeton pour Azure Time Series Insights en utilisant le langage C# et la bibliothèque de client d’identité Azure pour .NET :

using Azure.Identity;
// ...
var credential = new DefaultAzureCredential();
var token = credential.GetToken(
new Azure.Core.TokenRequestContext(
    new[] { "https://api.timeseries.azure.com/" }));
var accessToken = token.Token;

Enregistrement d’application

La MSAL est utilisable dans de nombreux scénarios d’application, dont les suivants :

Pour obtenir un exemple de code C# montrant comment obtenir un jeton en tant qu’inscription d’application, et interroger des données à partir d’un environnement Gen2, consultez l’exemple d’application sur GitHub.

Important

Si vous utilisez la Bibliothèque d’authentification Active Directory (ADAL) effectuez une migration vers MSAL.

Paramètres et en-têtes communs

Cette section décrit les en-têtes de requête HTTP et les paramètres qui sont couramment utilisés pour exécuter des requêtes sur les API Azure Time Series Insights Gen1 et Gen2. Les exigences spécifiques aux API sont décrites plus en détail dans la documentation de référence sur l’API REST Azure Time Series Insights.

Conseil

Lisez les Informations de référence sur l’API REST Azure pour en savoir plus sur l’utilisation des API REST, la création de requêtes HTTP et la gestion des réponses HTTP.

En-têtes HTTP

Les en-têtes de requête obligatoires sont décrits ci-dessous.

En-tête de requête obligatoire Description
Autorisation Pour l’authentification auprès d’Azure Time Series Insights, un jeton du porteur OAuth 2.0 valide doit être passé dans l’en-tête d’autorisation.

Conseil

Pour savoir comment s’authentifier par programmation auprès des API Azure Time Series Insights à l’aide du Kit de développement logiciel (SDK) JavaScript Client, lisez l’exemple de visualisation hébergé du Kit de développement logiciel (SDK) client Azure Time Series Insights ainsi que des graphes et autres graphiques.

Les en-têtes de requête facultatifs sont décrits ci-dessous.

En-tête de demande facultatif. Description
Content-Type Seul application/json est pris en charge.
x-ms-client-request-id ID de requête client. Le service enregistre cette valeur. Permet au service de suivre l’opération d’un service à l’autre.
x-ms-client-session-id ID de session du client. Le service enregistre cette valeur. Permet au service de suivre un groupe d’opérations connexes d’un service à l’autre.
x-ms-client-application-name Nom de l’application qui a généré cette requête. Le service enregistre cette valeur.

Les en-têtes de réponse facultatifs mais recommandés sont décrits ci-dessous.

En-tête de réponse Description
Content-Type Seul application/json est pris en charge.
x-ms-request-id ID de requête généré par le serveur. Peut être utilisé pour demander à Microsoft d’examiner une requête.
x-ms-property-not-found-behavior En-tête de réponse facultatif de l’API GA. Les valeurs possibles sont ThrowError (par défaut) ou UseNull.

Paramètres HTTP

Conseil

Pour plus d’informations sur les informations de requête obligatoires et facultatives, consultez la documentation de référence.

Les paramètres de chaîne de requête d’URL obligatoires dépendent de la version de l’API.

Libérer Valeurs de version d’API
Première génération api-version=2016-12-12
Deuxième génération api-version=2020-07-31

Les paramètres de chaîne de requête d’URL facultatifs incluent la définition d’un délai d’expiration pour les durées d’exécution des requêtes HTTP.

Paramètre de requête facultatif Description Version
timeout=<timeout> Délai d’attente côté serveur pour l’exécution des requêtes HTTP. S’applique uniquement aux API Get Environment Events et Get Environment Aggregates. La valeur du délai d’attente doit être au format de durée ISO 8601, par exemple "PT20S", et doit être comprise dans la plage 1-30 s. La valeur par défaut est 30 s. Première génération
storeType=<storeType> Pour les environnements Gen2 avec le magasin chaud activé, la requête peut être exécutée sur WarmStore ou ColdStore. Ce paramètre dans la requête définit le magasin sur lequel la requête doit être exécutée. S’il n’est pas défini, la requête est exécutée sur le magasin Cold. Pour interroger le magasin Warm, storeType doit être défini sur WarmStore. S’il n’est pas défini, la requête est exécutée par rapport au magasin Cold. Deuxième génération

Étapes suivantes