Partager via

Authentification et autorisation pour l’API Insights Azure Time Series

  • Article

Remarque

Le service Time Series Insights va être mis hors service le 7 juillet 2024. Prévoyez de migrer les environnements existants vers des solutions alternatives dès que possible. 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 Insights effectue l’authentification à l’aide de 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 permettant d’obtenir des informations d’identification, puis un jeton de porteur, afin de s’authentifier, ce qui comprend l’utilisation d’une identité managée et l’inscription d’une application Microsoft Entra.

Identités managées

Les sections suivantes décrivent comment utiliser une identité managée Microsoft Entra ID pour accéder à l’API Azure Time Series Insights. 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 d’un service Azure qui prend en charge l’authentification Microsoft Entra, notamment 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 prenant en charge les identités managées, vous pouvez inscrire votre application auprès d’un locataire Microsoft Entra. Lorsque vous inscrivez votre application auprès de Microsoft Entra ID, vous créez une configuration d’identité pour votre application, ce qui lui permet de s’intégrer à Microsoft Entra ID. 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 en savoir plus, consultez Objets de l’application et du 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é managé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 votre type d’identité sélectionné, 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.

    Créer des URI de redirection

    Cliquez sur Configurer, puis sur Enregistrer.

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

    Associer une API à votre application Microsoft Entra

    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.

    Spécifier le type d’autorisation d’API que votre application exige

  • 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 est nécessaire.

  • 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;

Inscription 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 vous authentifier par programmation auprès des API Azure Time Series Insights à l’aide du Kit de développement logiciel (SDK) JavaScript Client et obtenir des informations sur les graphes et les graphiques, lisez l’exemple de visualisation hébergé du SDK client Azure Time Series Insights.

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.

Version release 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