Authentification avec Azure Maps

Article
07/05/2023

Azure Maps prend en charge trois manières d’authentifier les requêtes : l’authentification par clé partagée, l’authentification Microsoft Entra ID et l’authentification par jeton SAP (signature d’accès partagé). Cet article décrit les méthodes d’authentification pour vous aider à effectuer votre implémentation des services Azure Maps. L’article décrit également les contrôles de compte supplémentaires, par exemple la désactivation de l’authentification locale pour Azure Policy et le partage de ressources cross-origin (CORS).

Notes

Pour sécuriser davantage la communication avec Azure Maps, nous prenons désormais en charge le protocole TLS 1.2 et ne prenons plus en charge les versions 1.0 et 1.1 de ce protocole. Si vous utilisez actuellement TLS 1.x, découvrez si vous êtes prêt à passer à TLS 1.2 et créez un plan de migration avec les tests décrits dans Résoudre les problèmes de dépendances TLS 1.0.

Authentification par clé partagée

Pour plus d’informations sur l’affichage de vos clés dans le portail Azure, consultez Voir les détails d’authentification.

Les clés primaires et secondaires sont générées après la création du compte Azure Maps. Nous vous encourageons à utiliser la clé primaire comme clé d’abonnement lors de l’appel d’Azure Maps avec l’authentification par clé partagée. L’authentification par clé partagée transmet une clé générée par un compte Azure Maps à un service Azure Maps. Pour chaque requête envoyée aux services Azure Maps, ajoutez la clé d’abonnement à l’URL en tant que paramètre. La clé secondaire peut être utilisée dans des scénarios tels que le roulement des changements de clés.

Exemple d’utilisation de la clé d’abonnement en tant que paramètre dans votre URL :

https://atlas.microsoft.com/mapData/upload?api-version=1.0&dataFormat=zip&subscription-key={Your-Azure-Maps-Subscription-key}

Important

Les clés primaires et secondaires doivent être traitées comme des données sensibles. La clé partagée est utilisée pour authentifier toutes les API REST Azure Maps. Les utilisateurs qui utilisent une clé partagée doivent faire abstraction de la clé API, soit via des variables d’environnement, soit un stockage secret sécurisé, où elles peuvent être gérées de manière centralisée.

Authentification Microsoft Entra

Les abonnements Azure sont fournis avec un locataire Microsoft Entra afin de permettre un contrôle d’accès affiné. Azure Maps offre une authentification pour les services Azure Maps à l’aide de Microsoft Entra ID. Microsoft Entra ID fournit une authentification basée sur l’identité pour les utilisateurs et les applications inscrits dans le locataire Microsoft Entra.

Azure Maps accepte les jetons d’accès OAuth 2.0 pour les locataires Microsoft Entra associés à un abonnement Azure comprenant un compte Azure Maps. Azure Maps accepte également les jetons pour :

Utilisateurs de Microsoft Entra
Applications partenaires qui utilisent des autorisations déléguées par des utilisateurs
Identités gérées pour les ressources Azure

Azure Maps génère un identificateur unique (ID client) pour chaque compte Azure Maps. Vous pouvez demander des jetons à Microsoft Entra ID lorsque vous combinez cet ID client avec d’autres paramètres.

Si vous souhaitez obtenir plus d’informations sur la configuration de Microsoft Entra ID et sur les requêtes de jetons pour Azure Maps, consultez Gérer l’authentification dans Azure Maps.

Pour obtenir des informations générales sur l’authentification auprès de Microsoft Entra ID, consultez Authentification ou autorisation.

Identités managées pour les ressources Azure et Azure Maps

Les identités managées pour les ressources Azure fournissent aux services Azure un principal de sécurité basé sur l’application et managé automatiquement qui peut s’authentifier auprès de Microsoft Entra ID. Avec le contrôle Azure d’accès en fonction du rôle (Azure RBAC), le principal de sécurité d’identités managées peut être autorisé à accéder aux services Azure Maps. Voici quelques exemples d’identités managées : Azure App Service, Azure Functions et Machines virtuelles Azure. Pour obtenir la liste des identités managées, consultez les Services Azure qui peuvent utiliser des identités managées pour accéder à d’autres services. Pour plus d’informations sur les identités managées, consultez Gérer l’authentification dans Azure Maps.

Configurer l’authentification de l’application Microsoft Entra

Les applications s’authentifient auprès du locataire Microsoft Entra par le biais d’un ou plusieurs scénarios pris en charge fournis par Microsoft Entra ID. Chaque scénario d’application Microsoft Entra représente des exigences différentes en fonction des besoins de l’entreprise. Certaines applications peuvent nécessiter des expériences de connexion utilisateur, tandis que d’autres peuvent nécessiter une expérience de connexion d’application. Pour plus d’informations, consultez Flux d’authentification et scénarios d’applications.

Une fois que l’application a reçu un jeton d’accès, le SDK et/ou l’application envoie une requête HTTPS avec l’ensemble suivant d’en-têtes HTTP requis en plus des autres en-têtes HTTP de l’API REST :

Nom de l’en-tête	Valeur
x-ms-client-id	30d7cc…9f55
Autorisation	Bearer eyJ0e….HNIVN

Notes

x-ms-client-id est le compte Azure Maps basé sur le GUID, qui apparaît dans la page d’authentification Azure Maps.

Voici un exemple de requête de routage Azure Maps qui utilise un jeton du porteur OAuth Microsoft Entra ID :

GET /route/directions/json?api-version=1.0&query=52.50931,13.42936:52.50274,13.43872
Host: atlas.microsoft.com
x-ms-client-id: 30d7cc….9f55
Authorization: Bearer eyJ0e…HNIVN

Pour plus d’informations sur l’affichage de votre ID client, consultez Voir les détails de l’authentification.

Conseil

Obtention de l’ID client par programmation

Quand vous utilisez PowerShell, l’ID client est stocké en tant que propriété UniqueId dans l’objet IMapsAccount. Vous récupérez cette propriété à l’aide de Get-AzMapsAccount, par exemple :

$maps = Get-AzMapsAccount -Name {Azure-Maps_Account-Name} -ResourceGroupName {Resource-Group-Name} -SubscriptionId {SubscriptionId}
$ClientId = $maps.UniqueId

Quand vous utilisez Azure CLI, utilisez la commande az maps account show avec le paramètre --query, par exemple :

$ClientId = az maps account show --name {Azure-Maps_Account-Name} --resource-group {Resource-Group-Name} --subscription {SubscriptionId} --query properties.uniqueId

Autorisation avec contrôle d’accès en fonction du rôle

Prérequis

Si vous découvrez le contrôle RBAC Azure, la vue d’ensemble Contrôle RBAC (contrôle d’accès en fonction du rôle) Azure décrit le jeu d’autorisations, également appelé définition de rôle, qui est octroyé aux types de principal. Une définition de rôle fournit des autorisations pour les actions de l’API REST. Azure Maps prend en charge l’accès à tous les types de principaux pour le contrôle d’accès en fonction du rôle Azure (Azure RBAC), notamment les utilisateurs Microsoft Entra, les groupes, les applications, les ressources Azure et les identités managées Azure. L’application de l’accès à un ou plusieurs comptes Azure Maps est appelée « étendue ». Une attribution de rôle est créée lorsqu’un principal, une définition de rôle et une étendue sont appliqués.

Vue d’ensemble

Les sections ci-après traitent des concepts et des composants de l’intégration d’Azure Maps à Azure RBAC. Dans le cadre du processus de configuration de votre compte Azure Maps, un répertoire Microsoft Entra est associé à l’abonnement Azure, dans lequel réside le compte Azure Maps.

Quand vous configurez Azure RBAC, vous choisissez un principal de sécurité et l’appliquez à une attribution de rôle. Pour découvrir comment ajouter des attributions de rôles dans le portail Azure, consultez Attribuer des rôles Azure avec le portail Azure.

Sélection d’une définition de rôle

Les types de définitions de rôles suivants sont disponibles pour prendre en charge les scénarios d’application.

Définition de rôle Azure	Description
Lecteur de données de recherche et d’affichage Azure Maps	Permet d’accéder uniquement aux API REST de recherche et d’affichage Azure Maps pour limiter l’accès aux cas d’usage de base du navigateur web.
Lecteur de données Azure Maps	Fournit l’accès aux API REST Azure Maps immuables.
Contributeur aux données Azure Maps	Fournit l’accès aux API REST Azure Maps mutables. La mutabilité, définie par les actions : écrire et supprimer.
Azure Maps rôle de lecture de données et de traitement par lots	Ce rôle peut être utilisé pour attribuer des actions de lecture et de traitement par lots sur Azure Maps.
Définition de rôle personnalisée	Créez un rôle conçu pour permettre un accès limité flexible aux API REST Azure Maps.

Certains services Azure Maps peuvent nécessiter des privilèges élevés pour effectuer des actions d’écriture ou de suppression sur les API REST Azure Maps. Le rôle Contributeur aux données Azure Maps est obligatoire pour les services qui effectuent des actions d’écriture ou de suppression. Le tableau suivant décrit les services auxquels s’applique le rôle Contributeur aux données Azure Maps lors d’actions d’écriture ou de suppression. Lorsque seules des actions de lecture sont nécessaires, le rôle Lecteur de données Azure Maps peut être utilisé à la place du rôle Contributeur aux données Azure Maps.

Service Azure Maps	Définition de rôle Azure Maps
Données	Contributeur aux données Azure Maps
Creator	Contributeur aux données Azure Maps
Spatial	Contributeur aux données Azure Maps
Recherches et Itinéraires par lots	Contributeur aux données Azure Maps

Pour plus d’informations sur la consultation de vos paramètres Azure RBAC, consultez Comment configurer le contrôle Azure RBAC pour Azure Maps.

Définitions de rôles personnalisées

L’un des aspects de la sécurité d’application est le principe du privilège minimum, pratique consistant à limiter les droits d’accès aux droits requis pour le travail actuel. La limitation des droits d’accès s’effectue en créant des définitions de rôle personnalisées qui prennent en charge les cas d’usage nécessitant une granularité accrue pour le contrôle d’accès. Pour créer une définition de rôle personnalisée, sélectionnez des actions de données spécifiques à inclure ou exclure pour la définition.

La définition de rôle personnalisée peut ensuite être utilisée dans une attribution de rôle pour n’importe quel principal de sécurité. Pour en savoir plus sur les définitions de rôles personnalisées Azure, consultez Rôles personnalisés Azure.

Voici quelques exemples de scénarios dans lesquels des rôles personnalisés peuvent améliorer la sécurité de l’application.

Scénario	Action(s) de données de rôles personnalisés
Une page web de connexion interactive ou publique avec des mosaïques de base et aucune autre API REST.	`Microsoft.Maps/accounts/services/render/read`
Une application qui nécessite uniquement un géocodage inversé, sans aucune autre API REST.	`Microsoft.Maps/accounts/services/search/read`
Un rôle pour un principal de sécurité qui demande la lecture de données cartographiques basées sur Azure Maps Creator et des API REST de mosaïques de base.	`Microsoft.Maps/accounts/services/data/read`, `Microsoft.Maps/accounts/services/render/read`
Un rôle pour un principal de sécurité qui nécessite la lecture, l’écriture et la suppression de données cartographiques basées sur le Créateur. Défini en tant que rôle d’éditeur de données de carte qui n’autorise pas l’accès à d’autres API REST comme les mosaïques de base.	`Microsoft.Maps/accounts/services/data/read`, `Microsoft.Maps/accounts/services/data/write`, `Microsoft.Maps/accounts/services/data/delete`

Comprendre la portée

Quand vous créez une attribution de rôle, elle est définie dans la hiérarchie de ressources Azure. Le haut de la hiérarchie figure un groupe d’administration, et tout en bas se trouve une ressource Azure, par exemple un compte Azure Maps. L’attribution d’une attribution de rôle à un groupe de ressources peut permettre l’accès à plusieurs comptes Azure Maps ou à plusieurs ressources du groupe.

Conseil

La recommandation générale de Microsoft consiste à attribuer l’accès à l’étendue de compte Azure Maps, car cela empêche tout accès involontaire à d’autres comptes Azure Maps existants dans le même abonnement Azure.

Désactiver l’authentification locale

Les comptes Azure Maps prennent en charge la propriété Azure standard dans l’API Management pour Microsoft.Maps/accounts appelée disableLocalAuth. Quand la valeur est true, toutes les authentifications auprès de l’API REST du plan de données Azure Maps sont désactivées, à l’exception de l’authentification Microsoft Entra. Vous pouvez configurer ce comportement à l’aide d’Azure Policy pour contrôler la distribution et la gestion des clés partagées et des jetons SAS. Pour plus d’informations, consultez Qu’est-ce qu’Azure Policy ?.

La désactivation de l’authentification locale ne prend pas effet immédiatement. Patientez quelques minutes avant que le service bloque les demandes d’authentification ultérieures. Pour réactiver l’authentification locale, affectez à la propriété la valeur false. Après quelques minutes, l’authentification locale reprend.

{
  // omitted other properties for brevity.
  "properties": {
    "disableLocalAuth": true
  }
}

Authentification par jeton de signature d’accès partagé

Les jetons SAS (signature d’accès partagé) sont des jetons d’authentification créés à l’aide du format JWT (JSON Web Token). Ils sont signés par chiffrement pour prouver l’authentification d’une application auprès de l’API REST Azure Maps. Un jeton SAS créé via l’intégration d’une identité managée affectée par l’utilisateur avec un compte Azure Maps dans votre abonnement Azure. L’identité managée affectée par l’utilisateur se voit octroyer une autorisation d’accès au compte Azure Maps via le contrôle RBAC Azure à l’aide des définitions de rôle intégrées ou personnalisées.

Différences de fonctionnement clés entre un jeton SAP et des jetons d’accès Microsoft Entra :

Durée de vie d’un jeton pour une expiration maximale d’un jour (24 heures).
Localisation Azure et contrôle d’accès géographique par jeton.
Limites de débit par jeton pour une valeur approximative comprise entre 1 et 500 requêtes par seconde.
Les clés privées du jeton sont les clés primaire et secondaire d’une ressource de compte Azure Maps.
L’objet de principal de service pour l’autorisation est fourni par une identité managée affectée par l’utilisateur.

Les jetons SAS sont immuables. Cela signifie qu’une fois qu’un jeton est créé, le jeton SAS est valide jusqu’à ce que le délai d’expiration soit atteint. De plus, la configuration des régions autorisées, les limites de débit et l’identité managée affectée par l’utilisateur ne peuvent pas être changées. Découvrez ci-dessous des informations supplémentaires liées à la compréhension du contrôle d’accès pour en savoir plus sur la révocation des jetons SAS et les changements apportés au contrôle d’accès.

Comprendre les limites de débit des jetons SAS

La limite de débit maximale d’un jeton SAS permet de contrôler la facturation d’une ressource Azure Maps

Quand vous spécifiez une limite de débit maximale pour le jeton (maxRatePerSecond), le taux excédentaire n’est pas facturé au compte, ce qui vous permet de définir une limite supérieure de transactions facturables pour le compte, quand vous utilisez le jeton. Toutefois, l’application reçoit les réponses d’erreur du client avec 429 (TooManyRequests) pour toutes les transactions, une fois cette limite atteinte. Il incombe à l’application de gérer les nouvelles tentatives et la distribution des jetons SAS. Il n’existe aucune limite au nombre de jetons SAS pouvant être créés pour un compte. Pour permettre une augmentation ou une diminution de la limite d’un jeton existant, un nouveau jeton SAP doit être créé. L’ancien jeton SAP est toujours valide jusqu’à son expiration.

Exemple d’estimation :

Débit maximal approximatif par seconde	Débit réel par seconde	Durée du débit continu en secondes	Nombre total de transactions facturables
10	20	600	6 000 / 750

Les limites de débit réelles varient en fonction de la capacité de Azure Maps à appliquer la cohérence pendant un intervalle de temps. Toutefois, cela permet un contrôle préventif des coûts de facturation.

Les limites de débit sont appliquées par localisation Azure, et non globalement ou géographiquement

Par exemple, un seul jeton SAS avec un maxRatePerSecond de 10 peut être utilisé pour limiter le débit dans East US. Si ce même jeton est utilisé dans West US 2, un compteur est créé pour limiter le débit à 10 au sein de cette localisation, indépendamment de la localisation East US. Pour contrôler les coûts et améliorer la prévisibilité, nous recommandons les choix suivants :

Créez des jetons SAS avec des localisations Azure autorisées pour une zone géographique ciblée. Poursuivez votre lecture pour comprendre le processus de création des jetons SAS.
Utilisez les points de terminaison d’API REST du plan de données géographique, https://us.atlas.microsoft.com ou https://eu.atlas.microsoft.com.

Tenez compte de la topologie d’application où le point de terminaison https://us.atlas.microsoft.com est routé vers les mêmes localisations aux États-Unis que celles où sont hébergés les services Azure Maps, par exemple East US, West Central US ou West US 2. La même idée s’applique aux autres points de terminaison géographiques, par exemple https://eu.atlas.microsoft.com entre West Europe et North Europe. Pour éviter les refus d’autorisation inattendus, utilisez un jeton SAP qui utilise les mêmes localisations Azure que celles consommées par l’application. La localisation du point de terminaison est définie à l’aide de l’API REST de gestion d’Azure Maps.

Les limites de débit par défaut sont prioritaires sur les limites de débit des jetons SAS

Comme indiqué dans les limites de débit d’Azure Maps, les offres de services individuelles ont des limites de débit variables qui sont appliquées sous forme d’agrégation du compte.

Prenons le cas de service Search : non-batch inverse, avec sa limite de 250 requêtes par seconde (RPS) pour les tables suivantes. Chaque table représente une estimation du nombre total de transactions réussies à partir de l’exemple d’utilisation.

La première table montre 1 jeton dont le nombre de requêtes maximales par seconde est de 500. L’utilisation réelle de l’application a été de 500 requêtes par seconde pendant une durée de 60 secondes. Le service Search : non-batch inverse a une limite de débit de 250, ce qui signifie que sur un total de 30 000 requêtes effectuées dans les 60 secondes, 15 000 d’entre elles sont des transactions facturables. Les requêtes restantes entraînent la génération du code d’état 429 (TooManyRequests).

Nom	Débit maximal approximatif par seconde	Débit réel par seconde	Durée du débit continu en secondes	Total approximatif des transactions réussies
token	500	500	60	~15 000

Par exemple, si deux jetons SAS sont créés et utilisent le même emplacement qu’un compte Azure Maps, chaque jeton partage désormais la limite de débit par défaut de 250 RPS (requêtes par seconde). Si chaque jeton est utilisé en même temps avec le même débit, le jeton 1 et le jeton 2 octroient chacun 7500 transactions réussies.

Name	Débit maximal approximatif par seconde	Débit réel par seconde	Durée du débit continu en secondes	Total approximatif des transactions réussies
jeton 1	250	250	60	~7 500
jeton 2	250	250	60	~7 500

Comprendre le contrôle d’accès par jeton SAS

Les jetons SAS utilisent RBAC pour contrôler l’accès à l’API REST. Quand vous créez un jeton SAS, l’identité managée nécessaire (prérequis) du compte Maps se voit attribuer un rôle RBAC Azure, qui octroie l’accès à des actions d’API REST spécifiques. Consultez Sélection d’une définition de rôle pour déterminer quelle est l’API qui est autorisée par l’application.

Si vous souhaitez affecter un accès temporaire et supprimer cet accès avant l’expiration du jeton SAS, révoquer le jeton. La révocation de l’accès peut également être motivée par le fait que le jeton est distribué avec l’attribution de rôle Azure Maps Data Contributor par inadvertance. Toute personne disposant du jeton SAS peut lire et écrire des données dans les API REST Azure Maps, ce qui peut exposer des données sensibles ou entraîner des coûts inattendus liés à l’utilisation.

il existe deux options pour révoquer l’accès des jetons SAS :

Générez à nouveau la clé utilisée par le jeton SAP ou la secondaryKey du compte Maps.
Supprimez l’attribution de rôle pour l’identité managée sur le compte Maps associé.

Avertissement

En cas de suppression d’une identité managée utilisée par un jeton SAS ou de révocation du contrôle d’accès de l’identité managée, les instances de votre application qui utilisent le jeton SAS et l’identité managée retournent intentionnellement 401 Unauthorized ou 403 Forbidden à partir des API REST Azure Maps, ce qui entraîne une interruption du fonctionnement de l’application.

Pour éviter toute interruption :

Ajoutez une deuxième identité managée au compte Maps, et octroyez à la nouvelle identité managée l’attribution de rôle appropriée.
Créez un jeton SAP à l’aide de secondaryKey, ou d’une identité managée différente de celle précédente, en tant que signingKey et distribuez le nouveau jeton SAP à l’application.
Regénérez la clé primaire, supprimez l’identité managée du compte, puis supprimez l’attribution de rôle pour l’identité managée.

Créer des jetons SAS

Pour créer des jetons SAS, vous devez disposer du rôle Contributor afin de gérer à la fois les comptes Azure Maps et les identités affectées par l’utilisateur dans l’abonnement Azure.

Important

Les comptes Azure Maps existants créés dans la localisation Azure global ne prennent pas en charge les identités managées.

Tout d’abord, vous devez créer une identité managée affectée par l’utilisateur dans la même localisation que le compte Azure Maps.

Conseil

Vous devez utiliser la même localisation pour l’identité managée et le compte Azure Maps.

Une fois qu’une identité managée est créée, vous pouvez créer ou mettre à jour le compte Azure Maps et l’attacher. Pour plus d’informations, consultez Gérer votre compte Azure Maps.

Une fois le compte créé ou mis à jour correctement avec l’identité managée appropriée, attribuez le contrôle d’accès en fonction du rôle de l’identité managée à un rôle de données Azure Maps au niveau de l’étendue du compte. Cela permet d’octroyer à l’identité managée l’accès à l’API REST Azure Maps pour votre compte Maps.

Créer ensuite un jeton SAS en utilisant les outils du kit SDK Azure Management, l’opération de listage des jetons SAS de l’API de gestion de compte ou la page Signature d’accès partagé du portail Azure de la ressource de compte Maps.

Paramètres du jeton SAS :

Nom du paramètre	Exemple de valeur	Description
signingKey	`primaryKey`	Obligatoire, la valeur d’enum de chaîne de signingKey, `primaryKey`, `secondaryKey` ou l’identité managée est utilisée pour créer la signature du jeton SAP.
principalId	`<GUID>`	Obligatoire, principalId est l’ID d’objet (principal) de l’identité managée affectée par l’utilisateur attachée au compte Maps.
regions	`[ "eastus", "westus2", "westcentralus" ]`	Facultatif, la valeur par défaut est `null`. Le paramètre regions permet de contrôler les régions où le jeton SAS peut être utilisé dans l’API de plan de données REST d’Azure Maps. L’omission du paramètre régions permet d’utiliser le jeton SAS sans aucune contrainte. Quand il est combiné avec un point de terminaison géographique de plan de données Azure Maps tel que `us.atlas.microsoft.com` et `eu.atlas.microsoft.com`, l’application peut contrôler l’utilisation au sein de la zone géographique spécifiée. Cela permet d’empêcher toute utilisation dans d’autres zones géographiques.
maxRatePerSecond	500	Obligatoire, permet de spécifier le débit maximal approximatif de requêtes par seconde octroyé au jeton SAS. Une fois la limite atteinte, le débit supplémentaire est limité avec le code d’état HTTP `429 (TooManyRequests)`.
start	`2021-05-24T10:42:03.1567373Z`	Obligatoire. Date UTC qui spécifie la date et l’heure auxquelles le jeton devient actif.
expiration	`2021-05-24T11:42:03.1567373Z`	Obligatoire. Date UTC qui spécifie la date et l’heure auxquelles le jeton arrive à expiration. La durée entre le début et l’expiration ne peut pas dépasser 24 heures.

Configuration d’une application avec un jeton SAS

Une fois que l’application a reçu un jeton SAS, le kit SDK Azure Maps et/ou les applications envoient une requête HTTPS avec l’en-tête HTTP nécessaire suivant en plus des autres en-têtes HTTP de l’API REST :

Nom de l’en-tête	Valeur
Autorisation	jwt-sas eyJ0e….HNIVN

Notes

jwt-sas est le schéma d’authentification à indiquer à l’aide d’un jeton SAS. N’incluez pas x-ms-client-id ou d’autres en-têtes d’autorisation, ni le paramètre de chaîne de requête subscription-key.

CORS est un protocole HTTP qui permet à une application web s’exécutant dans un domaine d’accéder aux ressources d’un autre domaine. Les navigateurs web implémentent une restriction de sécurité appelée stratégie de même origine qui empêche une page web d’appeler des API d’un autre domaine ; CORS constitue un moyen sûr pour autoriser un domaine (le domaine d’origine) à appeler des API d’un autre domaine. À l’aide de la ressource de compte Azure Maps, vous pouvez configurer les origines autorisées à accéder à l’API REST Azure Maps à partir de vos applications.

Important

CORS n’est pas un mécanisme d’autorisation. Toute requête adressée à un compte Maps à l’aide de l’API REST, quand CORS est activé, nécessite également un schéma d’authentification de compte Maps valide, par exemple une clé partagée, un jeton Microsoft Entra ID ou un jeton SAP.

CORS est pris en charge pour l’ensemble des niveaux tarifaires, points de terminaison de plan de données et emplacements de compte Maps.

Prérequis

Pour empêcher l’exécution de code malveillant sur le client, les navigateurs modernes bloquent les requêtes des applications web vers les ressources qui s’exécutent dans un domaine distinct.

Si vous n’êtes pas habitué à utiliser le partage CORS, consultez Partage de ressources cross-origin (CORS). Il permet à un en-tête Access-Control-Allow-Origin de déclarer les origines autorisées à appeler les points de terminaison d’un compte Azure Maps. Le protocole CORS n’est pas spécifique à Azure Maps.

Requêtes CORS

Une demande CORS d'un domaine d'origine peut comprendre deux demandes distinctes :

Une demande préliminaire, qui interroge les restrictions CORS imposées par le service. La requête préalable est obligatoire, sauf s’il s’agit d’une requête basée sur la méthode standard GET, HEAD, POST ou d’une requête contenant un en-tête de requête Authorization.
La demande réelle, adressée à la ressource souhaitée.

Demande préliminaire

La requête préalable est effectuée pour des raisons de sécurité afin de garantir que le serveur comprend la méthode et les en-têtes envoyés dans la requête réelle, et qu’il connaît la source de la requête et l’approuve. De plus, la requête préalable interroge les restrictions CORS établies pour le compte Maps. Le navigateur web (ou tout autre agent utilisateur) envoie une demande OPTIONS qui comprend les en-têtes de demande, la méthode et le domaine d'origine. Le service de compte Maps tente d’extraire les règles CORS si l’authentification du compte est possible via le protocole de contrôle préalable CORS.

Si l’authentification n’est pas possible, le service Maps évalue un ensemble préconfiguré de règles CORS qui spécifient les domaines d’origine, les méthodes de requête et les en-têtes de requête qui peuvent être indiqués dans une requête réelle destinée au service Maps. Par défaut, un compte Maps est configuré pour autoriser toutes les origines afin de permettre une intégration transparente aux navigateurs web.

Le service répond à la requête préalable avec les en-têtes de contrôle d’accès nécessaires si les critères suivants sont remplis :

La requête OPTIONS contient les en-têtes CORS nécessaires (les en-têtes Origin et Access-Control-Request-Method)
L’authentification a réussi, et une règle CORS est activée pour le compte qui correspond à la requête préalable.
L’authentification a été ignorée en raison d’en-têtes de requête Authorization obligatoires qui ne peuvent pas être spécifiés dans la requête préalable.

Quand la requête préalable réussit, le service répond avec le code d’état 200 (OK) et inclut les en-têtes Access-Control nécessaires dans la réponse.

Le service rejette les requêtes préalables si les conditions suivantes se présentent :

Si la demande OPTIONS ne contient pas les en-têtes CORS nécessaires (en-têtes Origin et Access-Control-Request-Method), le service répond avec le code d’état 400 (Bad request).
Si l’authentification a réussi pour la requête préalable et si aucune règle CORS ne lui correspond, le service répond par le code d’état 403 (Forbidden). Cela peut se produire si la règle CORS est configurée pour accepter une origine qui ne correspond pas à l’en-tête de requête Origin du client de navigateur.

Notes

Une requête préalable est évaluée par rapport au service et non par rapport à la ressource demandée. Le propriétaire du compte doit avoir activé CORS en définissant les propriétés de compte appropriées pour que la requête s’effectue correctement.

Demande réelle

Une fois la requête préalable acceptée et la réponse retournée, le navigateur envoie la requête réelle sur le service Maps. Le navigateur refuse immédiatement la demande réelle si la demande préliminaire est rejetée.

La requête réelle est traitée comme une requête normale adressée au service Maps. La présence de l’en-tête Origin indique que la requête est une requête CORS et que le service valide ensuite les règles CORS. Si une correspondance est trouvée, les en-têtes Access-Control sont ajoutés à la réponse et renvoyés au client. Si aucune correspondance n’est trouvée, la réponse renvoie un 403 (Forbidden), ce qui indique une erreur d’origine CORS.

Activer la stratégie CORS

Lorsqu’un compte Map est créé ou mis à jour, ses propriétés spécifient les origines autorisées à configurer. Vous pouvez définir une règle CORS pour les propriétés du compte Azure Maps via le kit SDK Azure Maps Management, l’API REST de gestion d’Azure Maps et le portail. Une fois que vous avez défini la règle CORS du service, une requête correctement autorisée et adressée au service à partir d’un autre domaine est évaluée pour déterminer si elle est autorisée conformément à la règle que vous avez spécifiée. Par exemple :

{
  "location": "eastus",
  "sku": {
    "name": "G2"
  },
  "kind": "Gen2",
  "properties": {
    "cors": {
      "corsRules": [
        {
          "allowedOrigins": [
            "https://www.azure.com",
            "https://www.microsoft.com"
          ]
        }
      ]
    }
  }
}

Une seule règle CORS avec sa liste d’origines autorisées peut être spécifiée. Chaque origine permet d’adresser la requête HTTP à l’API REST Azure Maps dans le navigateur web de l’origine spécifiée.

Supprimer la stratégie CORS

Vous pouvez supprimer CORS :

Manuellement dans le portail Azure
Par programmation, à l’aide de :
- Le SDK Azure Maps
- API REST de gestion Azure Maps
- Un modèle ARM

Conseil

Si vous employez l’API REST de gestion Azure Maps, utilisez PUT ou PATCH avec une liste corsRule vide dans le corps de la requête.

{
  "location": "eastus",
  "sku": {
    "name": "G2"
  },
  "kind": "Gen2",
  "properties": {
        "cors": {
          "corsRules": []
        }
    }
  }
}

Comprendre les transactions de facturation

Azure Maps ne compte pas les transactions de facturation pour les éléments suivants :

Codes d’état HTTP 5xx
401 (Non autorisé)
403 (Interdit)
408 (expiration)
429 (TooManyRequests)
Requêtes préliminaires CORS

Pour plus d’information sur les transactions de facturation ainsi que d’autre informations liées aux frais de Azure Maps, consultez Prix Azure Maps.

Étapes suivantes

Pour en savoir plus sur les meilleures pratiques en matière de sécurité, consultez :

Meilleures pratiques relatives à l’authentification et l’autorisation

Pour plus d’informations sur l’authentification d’une application avec Microsoft Entra ID et Azure Maps, consultez :

Gérer l’authentification dans Azure Maps

Pour plus d’informations sur l’authentification de contrôle Azure Maps avec Microsoft Entra ID, consultez :

Utiliser la bibliothèque Map Control d’Azure Maps

Authentification avec Azure Maps

Authentification par clé partagée

Authentification Microsoft Entra

Identités managées pour les ressources Azure et Azure Maps

Configurer l’authentification de l’application Microsoft Entra

Autorisation avec contrôle d’accès en fonction du rôle

Prérequis

Vue d’ensemble

Sélection d’une définition de rôle

Définitions de rôles personnalisées

Comprendre la portée

Désactiver l’authentification locale

Authentification par jeton de signature d’accès partagé

Comprendre les limites de débit des jetons SAS

La limite de débit maximale d’un jeton SAS permet de contrôler la facturation d’une ressource Azure Maps

Les limites de débit sont appliquées par localisation Azure, et non globalement ou géographiquement

Les limites de débit par défaut sont prioritaires sur les limites de débit des jetons SAS

Comprendre le contrôle d’accès par jeton SAS

Créer des jetons SAS

Configuration d’une application avec un jeton SAS

Partage de ressources cross-origin (CORS)

Prérequis

Requêtes CORS

Demande préliminaire

Demande réelle

Activer la stratégie CORS

Supprimer la stratégie CORS

Comprendre les transactions de facturation

Étapes suivantes

Ressources supplémentaires