Autenticación con Azure Maps

Artículo
07/05/2023

Azure Maps admite tres maneras de autenticar solicitudes: autenticación de clave compartida, autenticación de Microsoft Entra ID y autenticación de token de firma de acceso compartido (SAS). En este artículo se explican los métodos de autenticación como guía para implementar los servicios de Azure Maps. En el artículo también se describen otros controles de cuentas, como deshabilitar la autenticación local para Azure Policy y el uso compartido de recursos entre orígenes (CORS).

Nota

Para mejorar la comunicación segura con Azure Maps, ahora admitimos Seguridad de la capa de transporte (TLS) 1.2 y retiramos la compatibilidad con TLS 1.0 y 1.1. Si actualmente usa TLS 1.x, evalúe su preparación de TLS 1.2 y desarrolle un plan de migración con las pruebas descritas en Solución del problema de TLS 1.0.

Autenticación de clave compartida

Para obtener información sobre cómo ver sus claves en Azure Portal, consulte Ver detalles de autenticación.

Las claves principal y secundaria se generan después de crearse la cuenta de Azure Maps. Se recomienda usar la clave principal como clave de suscripción al llamar a Azure Maps mediante la autenticación de clave compartida. La autenticación de clave compartida pasa las claves generadas por una cuenta de Azure Maps a un servicio de Azure Maps. En solicitud a los servicios de Azure Maps requiere, agregue la clave de suscripción como parámetro a la dirección URL. La clave secundaria se puede usar, por ejemplo, para cambios de clave graduales.

Ejemplo de uso de la clave de suscripción como parámetro en la dirección URL:

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

Importante

Las claves principal y secundaria deben tratarse como datos confidenciales. La clave compartida se usa para autenticar todas las API de REST de Azure Maps. Los usuarios que usan una clave compartida deben abstraer la clave de API, bien a través de variables de entorno o del almacenamiento de secretos seguro, donde se puede administrar de forma centralizada.

Autenticación de Microsoft Entra

Se proporcionan suscripciones de Azure con un inquilino de Microsoft Entra para habilitar el control de acceso específico. Azure Maps ofrece autenticación para los servicios de Azure Maps mediante Microsoft Entra ID. Microsoft Entra ID proporciona autenticación basada en la identidad para los usuarios y las aplicaciones registradas en el inquilino de Microsoft Entra.

Azure Maps acepta tokens de acceso de OAuth 2.0 para inquilinos de Microsoft Entra asociados a suscripciones de Azure que contienen una cuenta de Azure Maps. Azure Maps también acepta tokens de:

Usuarios de Microsoft Entra
Aplicaciones de asociados que usan permisos delegados por los usuarios
Identidades administradas de recursos de Azure

Azure Maps genera un identificador único (id. de cliente) para cada cuenta de Azure Maps. Puede solicitar tokens de Microsoft Entra ID cuando combine este identificador de cliente con otros parámetros.

Para más información sobre cómo configurar Microsoft Entra ID y solicitar tokens para Azure Maps, consulte Administración de la autenticación en Azure Maps.

Para obtener información general sobre la autenticación con Microsoft Entra ID, consulte Autenticación frente a autorización.

Identidades administradas para recursos de Azure y Azure Maps

Las identidades administradas para recursos de Azure proporcionan a los servicios de Azure una entidad de seguridad basada en aplicaciones administrada automáticamente que se puede autenticar con Microsoft Entra ID. Con el control de acceso basado en rol de Azure (RBAC de Azure), se puede autorizar el acceso de la entidad de seguridad de la identidad administrada a los servicios de Azure Maps. Algunos ejemplos de identidades administradas son: Azure App Service, Azure Functions y Azure Virtual Machines. Para obtener una lista de identidades administradas, consulte los servicios de Azure que pueden usar identidades administradas para acceder a otros servicios. Para obtener más información sobre las identidades administradas, vea Administración de la autenticación en Azure Maps.

Configurar la autenticación de Microsoft Entra de la aplicación

Las aplicaciones se autentican con el inquilino de Microsoft Entra con uno o varios escenarios admitidos proporcionados por Microsoft Entra ID. Cada escenario de aplicación de Microsoft Entra representa requisitos diferentes en función de las necesidades empresariales. Es posible que algunas aplicaciones requieran experiencias de inicio de sesión de usuario y otras aplicaciones requieran una experiencia de inicio de sesión de aplicación. Para más información, consulte Flujos de autenticación y escenarios de aplicaciones.

Después de que la aplicación recibe un token de acceso, el SDK o la aplicación envían una solicitud HTTPS con el siguiente conjunto de encabezados HTTP necesarios, además de otros encabezados HTTP de la API REST:

Nombre de encabezado	Value
x-ms-client-id	30d7cc…9f55
Autorización	Bearer eyJ0e….HNIVN

Nota

x-ms-client-id es el GUID basado en la cuenta de Azure Maps que aparece en la página de autenticación de Azure Maps.

A continuación se muestra un ejemplo de una solicitud de ruta de Azure Maps que usa un token de portador de OAuth de 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

Para información sobre cómo ver el identificador de cliente, consulte Visualización de los detalles de la autenticación.

Sugerencia

Obtención del identificador de cliente mediante programación

Cuando se usa PowerShell, el id. de cliente se almacena como la propiedad UniqueId en el objeto IMapsAccount. Esta propiedad se recupera mediante Get-AzMapsAccount, por ejemplo:

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

Al usar la CLI de Azure, se utiliza el comando az maps account show con el parámetro --query, por ejemplo:

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

Autorización con el control de acceso basado en rol

Requisitos previos

Si es su primera vez con RBAC de Azure, la información general sobre el Control de acceso basado en roles de Azure (RBAC de Azure) proporciona a los tipos de entidades de seguridad un conjunto de permisos, también conocido como definición de roles. Una definición de roles proporciona permisos para las acciones de la API REST. Azure Maps admite el acceso a todos los tipos de entidad de seguridad para el control de acceso basado en rol de Azure (RBAC de Azure), por ejemplo, usuarios individuales de Microsoft Entra, grupos, aplicaciones, recursos de Azure e identidades administradas de Azure. La aplicación del acceso a una o varias cuentas de Azure Maps se conoce como ámbito. Al aplicar una entidad de seguridad, una definición de roles y un ámbito, se crea una asignación de roles.

Información general

En las secciones siguientes se habla de los conceptos y componentes de la integración de Azure Maps con RBAC de Azure. Como parte del proceso de configuración de la cuenta de Azure Maps, se asocia un directorio de Microsoft Entra a la suscripción de Azure en la que reside la cuenta de Azure Maps.

Al configurar RBAC de Azure, elija una entidad de seguridad y aplíquela a una asignación de roles. Para más información sobre cómo agregar asignaciones de roles en Azure Portal, consulte Asignación de roles de Azure mediante Azure Portal.

Selección de una definición de roles

Existen los siguientes tipos de definición de roles para admitir los distintos escenarios de aplicación.

Definición de roles de Azure	Descripción
Lector de datos de búsqueda y representación de Azure Maps	Proporciona acceso solo a las API de REST de búsqueda y representación de Azure Maps para limitar el acceso a los casos de uso básicos del explorador web.
Azure Maps Data Reader	Proporciona acceso a las API REST Azure Maps inmutables.
Colaborador de datos de Azure Maps	Proporciona acceso a las API REST de Azure Maps mutables. La mutabilidad se define mediante las acciones: escritura y eliminación.
Rol de lote y lectura de datos de Azure Maps	Este rol se puede usar para asignar acciones de lectura y por lotes en Azure Maps.
Definición de roles personalizados	Cree un rol diseñado para permitir un acceso restringido flexible a las API REST de Azure Maps.

Algunos servicios de Azure Maps pueden requerir privilegios elevados para realizar acciones de escritura o eliminación en las API REST de Azure Maps. El rol Colaborador de datos de Azure Maps es necesario para los servicios que proporcionan acciones de escritura o eliminación. En la tabla siguiente se describen los servicios a los que se aplica el rol Colaborador de datos de Azure Maps cuando se usan acciones de escritura o eliminación. Cuando solo se requieren acciones de lectura, el rol de lector de datos de Azure Maps se puede usar en lugar del rol de Colaborador de datos de Azure Maps.

Servicio de Azure Maps	Definición de roles de Azure Maps
Data	Colaborador de datos de Azure Maps
Creador	Colaborador de datos de Azure Maps
Espacial	Colaborador de datos de Azure Maps
Búsqueda y enrutamiento por lotes	Colaborador de datos de Azure Maps

Para obtener información sobre la visualización de la configuración de RBAC, vea Configuración de RBAC de Azure para Azure Maps.

Definiciones de roles personalizados

Un aspecto de la seguridad de las aplicaciones es el principio de privilegios mínimos, que supone la práctica de limitar los derechos necesarios para el trabajo actual. Para limitar los derechos de acceso, se crean definiciones de roles personalizadas que admiten casos de uso que requieren una mayor granularidad para el control de acceso. Para crear una definición de roles personalizados, puede seleccionar acciones de datos específicas para incluir o excluir de la definición.

La definición de roles personalizados se puede usar en una asignación de roles para cualquier entidad de seguridad. Para más información sobre las definiciones de roles personalizados de Azure, consulte Roles personalizados de Azure.

Estos son algunos escenarios de ejemplo en los que los roles personalizados pueden mejorar la seguridad de la aplicación.

Escenario	Acciones de datos del rol personalizado
Una página web de inicio de sesión interactiva o con orientación al público con mosaicos de mapa base y ninguna otra API REST.	`Microsoft.Maps/accounts/services/render/read`
Una aplicación que solo requiere geocodificación inversa y ninguna otra API de REST.	`Microsoft.Maps/accounts/services/search/read`
Un rol para una entidad de seguridad que solicita la lectura de los datos de un mapa basado en Azure Maps Creator y las API REST de mosaicos de mapa base.	`Microsoft.Maps/accounts/services/data/read`, `Microsoft.Maps/accounts/services/render/read`
Un rol para una entidad de seguridad que requiere la lectura, escritura y eliminación de datos de un mapa basado en Creator. Se define como un rol de editor de datos de mapa que no permite el acceso a otra API de REST, como los mosaicos de mapa base.	`Microsoft.Maps/accounts/services/data/read`, `Microsoft.Maps/accounts/services/data/write`, `Microsoft.Maps/accounts/services/data/delete`

Descripción del ámbito

Al crear una asignación de roles, se define dentro de la jerarquía de recursos de Azure. La parte superior de la jerarquía es un grupo de administración y en la inferior hay un recurso de Azure, como una cuenta de Azure Maps. Asignar una asignación de roles a un grupo de recursos puede permitir el acceso a varias cuentas de Azure Maps o a los recursos del grupo.

Sugerencia

La recomendación general de Microsoft consiste en asignar acceso al ámbito de la cuenta de Azure Maps porque impide el acceso no deseado a otras cuentas de Azure Maps existentes en la misma suscripción de Azure.

Deshabilitación de la autenticación local

Las cuentas de Azure Maps admiten la propiedad estándar de Azure en la API de administración para Microsoft.Maps/accounts denominada disableLocalAuth. Cuando es true, se deshabilita toda la autenticación en la API REST de plano de datos de Azure Maps, excepto la autenticación de Microsoft Entra. Esto se configura mediante Azure Policy para controlar la distribución y administración de claves compartidas y tokens de SAS. Para obtener más información, consulte ¿Qué es Azure Policy?

La deshabilitación de la autenticación local no tiene efecto inmediato. Espere unos minutos para que el servicio bloquee las solicitudes de autenticación futuras. Para volver a habilitar la autenticación local, establezca la propiedad en false y, después de unos minutos, se reanuda la autenticación local.

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

Autenticación con tokens de firma de acceso compartido (SAS)

Los tokens de firma de acceso compartido (SAS) son tokens de autenticación creados con el formato JSON Web Token (JWT) y están firmados criptográficamente para demostrar la autenticación de una aplicación en la API de REST de Azure Maps. Un token de SAS, creado mediante la integración de una identidad administrada asignada por el usuario con una cuenta de Azure Maps en la suscripción de Azure. La identidad administrada asignada por el usuario tiene autorización para la cuenta de Azure Maps a través de RBAC de Azure mediante una de las definiciones de roles integradas o personalizadas.

Diferencias clave funcionales entre el token de SAS y los tokens de acceso de Microsoft Entra:

Duración de un token con una expiración máxima de 1 día (24 horas).
Control de acceso de ubicación y zona geográfica de Azure por token.
Límites de frecuencia por token de 1 a 500 solicitudes por segundo, aproximadamente.
Las claves privadas del token son las claves principales y secundarias de un recurso de cuenta de Azure Maps.
Una identidad administrada asignada por el usuario proporciona el objeto de entidad de servicio para la autorización.

Los tokens de SAS son inmutables. Esto significa que, una vez creado un token, el token de SAS es válido hasta que se cumple la fecha de expiración y no se puede cambiar la configuración de las regiones permitidas, los límites de frecuencia y la identidad administrada asignada por el usuario. Obtenga más información a continuación sobre el funcionamiento del control de acceso para la revocación de tokens de SAS y los cambios en el control de acceso.

Funcionamiento de los límites de frecuencia de los tokens de SAS

El límite de frecuencia máxima del token de SAS puede controlar la facturación de un recurso de Azure Maps.

Al especificar un límite de frecuencia máxima en el token (maxRatePerSecond), la tarifa por el exceso no se factura a la cuenta, lo que le permitirá establecer un límite superior de transacciones facturables para la cuenta al usar el token. Sin embargo, la aplicación recibe respuestas de error de cliente con 429 (TooManyRequests) para todas las transacciones una vez que se alcance el límite. Es responsabilidad de la aplicación administrar los reintentos y la distribución de tokens de SAS. No hay ningún límite en el número de tokens de SAS que se pueden crear para una cuenta. Para permitir un aumento o una disminución del límite de un token existente, debe crearse un token de SAS. El token de SAS antiguo sigue siendo válido hasta su expiración.

Ejemplo estimado:

Frecuencia máxima aproximada por segundo	Frecuencia real por segundo	Duración de la velocidad sostenida en segundos	Total de transacciones facturables
10	20	600	6,000

Los límites de velocidad reales varían en función de la capacidad de Azure Maps de aplicar la coherencia en un intervalo de tiempo. Sin embargo, esto permite el control preventivo del coste de facturación.

Los límites de velocidad se aplican por ubicación de Azure, no de forma global ni geográfica

Por ejemplo, se puede usar un token de SAS único con un valor maxRatePerSecond de 10 para limitar el rendimiento en la ubicación East US. Si se usa ese mismo token en West US 2, se crea un nuevo contador para limitar el rendimiento a 10 en esa ubicación, independientemente de la ubicación East US. Para controlar los costes y mejorar la previsibilidad, se recomienda:

Crear tokens de SAS con ubicaciones de Azure permitidas designadas para la zona geográfica de destino. Siga leyendo para conocer la creación de tokens de SAS.
Usar puntos de conexión de la API de REST del plano de datos geográficos, https://us.atlas.microsoft.com o https://eu.atlas.microsoft.com.

Considere la topología de aplicación en la que el punto de conexión https://us.atlas.microsoft.com se enruta a las mismas ubicaciones de EE. UU. en las que se hospedan los servicios de Azure Maps, como East US, West Central US o West US 2. La misma idea se aplica a otros puntos de conexión geográficos, como https://eu.atlas.microsoft.com entre West Europe y North Europe. Para evitar denegaciones de autorización inesperadas, use un token de SAS que utilice las mismas ubicaciones de Azure que consume la aplicación. La ubicación del punto de conexión se define mediante la API de REST de administración de Azure Maps.

Los límites de velocidad predeterminados tienen preferencia frente a los límites de velocidad de tokens de SAS

Tal como se describe en Límites de frecuencia de Azure Maps, las ofertas de servicio individuales tienen límites de frecuencia variables que se aplican como agregado de la cuenta.

Considere el caso de Servicio Search: inverso sin lote, con su límite de 250 consultas por segundo (QPS) para las tablas siguientes. Cada tabla representa el total estimado de transacciones correctas a partir del uso de ejemplo.

En la primera tabla se muestra un token que tiene una solicitud máxima por segundo de 500 y el uso real de la aplicación es de 500 solicitudes por segundo durante 60 segundos. Servicio Search: inverso sin lote tiene un límite de frecuencia de 250, lo que significa que del total de 30 000 solicitudes realizadas en los 60 segundos, 15 000 de esas solicitudes son transacciones facturables. Las solicitudes restantes dan como resultado el código de estado 429 (TooManyRequests).

Nombre	Frecuencia máxima aproximada por segundo	Frecuencia real por segundo	Duración de la frecuencia sostenida en segundos	Total aproximado de transacciones correctas
token	500	500	60	~15 000

Por ejemplo, si se crean dos tokens de SAS y se usa la misma ubicación que una cuenta de Azure Maps, cada token ahora comparte el límite de frecuencia predeterminado de 250 QPS. Si cada token se usa al mismo tiempo con el mismo rendimiento, los tokens 1 y 2 concederían correctamente 7500 transacciones correctas cada uno.

Nombre	Frecuencia máxima aproximada por segundo	Frecuencia real por segundo	Duración de la frecuencia sostenida en segundos	Total aproximado de transacciones correctas
token 1	250	250	60	~7500
token 2	250	250	60	~7500

Funcionamiento del control de acceso con tokens de SAS

Los tokens de SAS usan RBAC para controlar el acceso a la API de REST. Al crear un token de SAS, a la identidad administrada de requisitos previos en la cuenta de Azure Maps se le asigna un rol RBAC de Azure que concede acceso a acciones específicas de la API REST. Consulte Selección de una definición de roles para determinar qué API permite la aplicación.

Si quiere asignar acceso temporal y quitar el acceso antes de que expire el token de SAS, revoque el token. Otras razones para revocar el acceso pueden ser si el token se distribuye con asignación de roles Azure Maps Data Contributor de forma involuntaria y cualquier persona con el token de SAS puede leer y escribir datos en las API REST de Azure Maps, lo que pueden exponer datos confidenciales o suponer costes financieros inesperados por el uso.

Hay dos opciones para revocar el acceso a los tokens de SAS:

Regenerar la clave que usó el token de SAS o secondaryKey de la cuenta de Azure Maps.
Quitar la asignación de roles para la identidad administrada en la cuenta de Azure Maps asociada.

Advertencia

La eliminación de una identidad administrada usada por un token de SAS o la revocación del control de acceso de la identidad administrada provocará que las instancias de la aplicación que utilicen el token de SAS y la identidad administrada devuelvan intencionadamente 401 Unauthorized o 403 Forbidden a través de las API de REST de Azure Maps, lo que creará una interrupción de la aplicación.

Para evitar las interrupciones:

Agregue una segunda identidad administrada a la cuenta de Azure Maps y conceda a la nueva identidad administrada la asignación de roles correcta.
Cree un token de SAS mediante secondaryKey o una identidad administrada diferente a la anterior, ya que el signingKey y distribuya el nuevo token de SAS a la aplicación.
Vuelva a generar la clave principal, quite la identidad administrada de la cuenta y quite la asignación de roles para la identidad administrada.

Creación de tokens de SAS

Para crear tokens de SAS, debe tener acceso de rol Contributor a fin de administrar cuentas de Azure Maps e identidades asignadas por el usuario en la suscripción de Azure.

Importante

Las cuentas de Azure Maps existentes creadas en la ubicación de Azure global no admiten las identidades administradas.

En primer lugar, debe crear una identidad administrada asignada por el usuario en la misma ubicación que la cuenta de Azure Maps.

Sugerencia

Debe usar la misma ubicación para la identidad administrada y la cuenta de Azure Maps.

Una vez creada una identidad administrada, puede crear o actualizar la cuenta de Azure Maps y asociarla. Para obtener más información, consulte Administrar la cuenta de Azure Maps.

Una vez que la cuenta se ha creado o actualizado correctamente con la identidad administrada, asigne el control de acceso basado en roles para la identidad administrada a un rol de datos de Azure Maps en el ámbito de la cuenta. Esto permite que a la identidad administrada se le proporcione acceso a la API de REST de Azure Maps para la cuenta de Azure Maps.

A continuación, cree un token de SAS mediante las herramientas del SDK de administración de Azure, la operación de enumerar SAS en la API de administración de la cuenta o la página Firma de acceso compartido de Azure Portal del recurso de la cuenta de Azure Maps.

Parámetros del token de SAS:

Nombre de parámetro	Valor de ejemplo	Descripción
signingKey	`primaryKey`	Obligatorio, el valor de enumeración de cadenas para signingKey `primaryKey`, `secondaryKey` o identidad administrada se usa para crear la firma de la SAS.
principalId	`<GUID>`	Obligatorio, principalId es el id. de objeto (entidad de seguridad) de la identidad administrada asignada por el usuario asociada a la cuenta de mapa.
regions	`[ "eastus", "westus2", "westcentralus" ]`	Opcional, el valor predeterminado es `null`. El parámetro regions controla qué regiones puede usar el token de SAS en la API REST de plano de datos de Azure Maps. La omisión del parámetro regions permite usar el token de SAS sin restricciones. Cuando se usa en combinación con un punto de conexión geográfico de plano de datos de Azure Maps como `us.atlas.microsoft.com` y `eu.atlas.microsoft.com` permite que la aplicación controle el uso en la zona geográfica especificada. Esto permite impedir el uso en otras zonas geográficas.
maxRatePerSecond	500	Obligatorio, solicitudes máximas aproximadas especificadas por segundo que se conceden al token de SAS. Una vez alcanzado el límite, el rendimiento adicional tiene una limitación de frecuencia con el código de estado HTTP `429 (TooManyRequests)`.
start	`2021-05-24T10:42:03.1567373Z`	Obligatorio, fecha UTC que especifica la fecha y hora en la que se activa el token.
expiry	`2021-05-24T11:42:03.1567373Z`	Obligatorio, fecha UTC que especifica la fecha y hora en la que expira el token. La duración entre el inicio y la expiración no puede ser superior a 24 horas.

Configuración de la aplicación con un token de SAS

Después de que la aplicación recibe un token de SAS, el SDK de Azure Maps o las aplicaciones envían una solicitud HTTPS con el siguiente encabezado HTTP obligatorio, además de otros encabezados HTTP de la API de REST:

Nombre de encabezado	Value
Authorization	jwt-sas eyJ0e….HNIVN

Nota

jwt-sas es el esquema de autenticación que se va a indicar mediante el token de SAS. No incluya x-ms-client-id ni otros encabezados de autorización ni el parámetro de cadena de consulta subscription-key.

CORS es un protocolo de HTTP que permite que una aplicación web que se ejecuta en un dominio tenga acceso a recursos de otro dominio. Los exploradores web implementan una restricción de seguridad denominada directiva del mismo origen que impide que una página web llame a las API de otro dominio diferente; CORS proporciona una forma segura de permitir que un dominio (el dominio de origen) llame a las API de otro dominio. Con el recurso de la cuenta de Azure Maps, puede configurar qué orígenes pueden tener acceso a la API REST de Azure Maps desde las aplicaciones.

Importante

CORS no es un mecanismo de autorización. Cualquier solicitud realizada a una cuenta de Azure Maps mediante la API de REST cuando CORS está habilitado también necesita un esquema de autenticación de cuenta de Azure Maps válido, como una clave compartida, Microsoft Entra ID o un token de SAS.

CORS es compatible con todos los planes de tarifa de cuentas de Azure Maps, puntos de conexión del plano de datos y ubicaciones.

Requisitos previos

Para evitar la ejecución de código malintencionado en el cliente, los exploradores modernos bloquean las solicitudes de las aplicaciones web en los recursos que se ejecutan en un dominio independiente.

Si no conoce bien CORS, vea Uso compartido de recursos entre orígenes (CORS); permite que un encabezado Access-Control-Allow-Origin declare qué orígenes pueden llamar a los puntos de conexión de una cuenta de Azure Maps. El protocolo CORS no es específico de Azure Maps.

Solicitudes de CORS

Una solicitud de CORS de un dominio de origen puede estar formada por dos solicitudes diferentes:

Una solicitud preparatoria, que consulta las restricciones de CORS impuestas por el servicio. La solicitud preparatoria es necesaria a menos que la solicitud sea el método estándar GET, HEAD, POST o que se trate de solicitudes que contengan el encabezado de solicitud Authorization.
La solicitud real, realizada en el recurso deseado.

Solicitud preparatoria

La solicitud preparatoria se hace no solo como medida de seguridad para asegurarse de que el servidor entiende el método y los encabezados que se envían en la solicitud real y que el servidor conoce y confía en el origen de la solicitud, sino que también consulta las restricciones de CORS que se han establecido para la cuenta de Azure Maps. El explorador web (u otro agente de usuario) envía una solicitud OPTIONS que incluye los encabezados, el método y el dominio de origen de la solicitud. El servicio de la cuenta de Azure Maps intenta recuperar las reglas de CORS si la autenticación de cuenta es posible a través del protocolo de preparación de CORS.

Si la autenticación no es posible, el servicio de mapas evalúa un conjunto preconfigurado de reglas de CORS que especifican qué dominios de origen, métodos de solicitud y encabezados de solicitud se pueden especificar en una solicitud real para el servicio de mapas. De forma predeterminada, una cuenta de Azure Maps está configurada para permitir que todos los orígenes habiliten la integración perfecta en los exploradores web.

El servicio responde a la solicitud preparatoria con los encabezados Access-Control necesarios si se cumplen los criterios siguientes:

La solicitud OPTIONS contiene los encabezados de CORS necesarios (los encabezados Origin y Access-Control-Request-Method).
La autenticación se ha hecho correctamente y se ha habilitado una regla de CORS para la cuenta que coincide con la solicitud preparatoria.
La autenticación se ha omitido porque hay encabezados de solicitud Authorization necesarios que no se pueden especificar en la solicitud preparatoria.

Cuando la solicitud preparatoria es correcta, el servicio responde con el código de estado 200 (OK) e incluye los encabezados Access-Control necesarios en la respuesta.

El servicio rechaza las solicitudes preparatorias si se producen las siguientes situaciones:

Si la solicitud OPTIONS no contiene los encabezados de CORS necesarios (los encabezados Origin y Access-Control-Request-Method), el servicio responde con el código de estado 400 (Bad request).
Si la autenticación ha sido correcta en la solicitud preparatoria y ninguna regla de CORS coincide con la solicitud preparatoria, el servicio responde con el código de estado 403 (Forbidden). Esto puede ocurrir si la regla de CORS está configurada para aceptar un origen que no coincide con el encabezado de solicitud de origen del cliente del explorador actual.

Nota

Una solicitud preparatoria se evalúa en el servicio y no en el recurso solicitado. El propietario de la cuenta tiene que haber habilitado CORS definiendo las propiedades de la cuenta correspondientes para que la solicitud sea correcta.

Solicitud real

Una vez que la solicitud preparatoria se acepte y se devuelva una respuesta, el explorador envía la solicitud real al servicio de Azure Maps. El explorador deniega inmediatamente la solicitud real si se rechazó la solicitud preparatoria.

La solicitud real se trata como una solicitud normal en el servicio de Azure Maps. La presencia del encabezado Origin indica que se trata de una solicitud CORS y el servicio valida las reglas de CORS. Si se encuentra una coincidencia, los encabezados Access-Control se agregan a la respuesta y se devuelven al cliente. Si no se encuentra una coincidencia, la respuesta devuelve un valor 403 (Forbidden), que indica un error de origen de CORS.

Habilitación de la directiva de CORS

Cuando se crea o actualiza una cuenta de Azure Maps, sus propiedades especifican los orígenes permitidos que se van a configurar. Puede establecer una regla de CORS en las propiedades de la cuenta de Azure Maps a través del SDK de administración de Azure Maps, la API de REST de administración de Azure Maps y el portal. Una vez establecidas las reglas de CORS para el servicio, se evalúa una solicitud autorizada correctamente enviada al servicio desde un dominio diferente a fin de determinar si se permite según la regla que ha especificado. Por ejemplo:

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

Solo se puede especificar una regla de CORS con su lista de orígenes permitidos. Cada origen permite enviar la solicitud HTTP a la API de REST de Azure Maps en el explorador web del origen especificado.

Eliminación de la directiva de CORS

Puede quitar CORS:

Manualmente en Azure Portal
Mediante programación con:
- El SDK de Azure Maps
- API de REST de administración de Azure Maps
- Una plantilla de ARM

Sugerencia

Si usa la API de REST de administración de Azure Maps, utilice PUT o PATCH con una lista corsRule vacía en el cuerpo de la solicitud.

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

Funcionamiento de las transacciones de facturación

Azure Maps no cuenta las transacciones de facturación para lo siguiente:

Códigos de estado HTTP 5xx
401 (No autorizado)
403 (Prohibido)
408 (tiempo de expiración)
429 (TooManyRequests)
Solicitudes CORS de preflight

Para obtener información adicional sobre las transacciones de facturación, así como otra información de precios de Azure Maps, vea Precios de Azure Maps.

Pasos siguientes

Para obtener más información sobre los procedimientos recomendados de seguridad, vea lo siguiente:

Procedimientos recomendados de autenticación y autorización

Para más información sobre la autenticación de una aplicación con Microsoft Entra ID y Azure Maps, consulte:

Administración de la autenticación en Azure Maps

Para más información sobre la autenticación del Control de mapa de Azure Maps con Microsoft Entra ID, consulte:

Uso del Control de mapa de Azure Maps

Autenticación con Azure Maps

Autenticación de clave compartida

Autenticación de Microsoft Entra

Identidades administradas para recursos de Azure y Azure Maps

Configurar la autenticación de Microsoft Entra de la aplicación

Autorización con el control de acceso basado en rol

Requisitos previos

Información general

Selección de una definición de roles

Definiciones de roles personalizados

Descripción del ámbito

Deshabilitación de la autenticación local

Autenticación con tokens de firma de acceso compartido (SAS)

Funcionamiento de los límites de frecuencia de los tokens de SAS

El límite de frecuencia máxima del token de SAS puede controlar la facturación de un recurso de Azure Maps.

Los límites de velocidad se aplican por ubicación de Azure, no de forma global ni geográfica

Los límites de velocidad predeterminados tienen preferencia frente a los límites de velocidad de tokens de SAS

Funcionamiento del control de acceso con tokens de SAS

Creación de tokens de SAS

Configuración de la aplicación con un token de SAS

Uso compartido de recursos entre orígenes (CORS)

Requisitos previos

Solicitudes de CORS

Solicitud preparatoria

Solicitud real

Habilitación de la directiva de CORS

Eliminación de la directiva de CORS

Funcionamiento de las transacciones de facturación

Pasos siguientes

Recursos adicionales