CORS

  • Artículo

SE APLICA A: todos los niveles de API Management

La directiva cors agrega compatibilidad con el uso compartido de recursos entre orígenes (CORS) a una operación o a una API para permitir llamadas entre dominios desde clientes basados en explorador.

Nota

Establezca los elementos de la directiva y los elementos secundarios en el orden proporcionado en la instrucción de directiva. Para que pueda configurar esta directiva, el portal proporciona un editor guiado basado en formularios. Obtenga más información sobre el establecimiento o modificación de directivas de API Management.

Instrucción de la directiva

<cors allow-credentials="false | true" terminate-unmatched-request="true | false">
    <allowed-origins>
        <origin>origin uri</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="number of seconds">
        <method>HTTP verb</method>
    </allowed-methods>
    <allowed-headers>
        <header>header name</header>
    </allowed-headers>
    <expose-headers>
        <header>header name</header>
    </expose-headers>
</cors>

Atributos

Asignar nombre Descripción Necesario Valor predeterminado
allow-credentials El encabezado Access-Control-Allow-Credentials de la respuesta preparatoria se establecerá en el valor de este atributo e influirá en la capacidad del cliente de enviar credenciales en solicitudes entre dominios. Se permiten expresiones de directiva. No false
terminate-unmatched-request Controla el procesamiento de solicitudes entre orígenes que no coinciden con la configuración de directiva. Se permiten expresiones de directiva.

Cuando la OPTIONSsolicitud se procesa como una solicitud preparatoria y Origin el encabezado no coincide con la configuración de la directiva:
- Si el atributo se establece en true, finalice inmediatamente la solicitud con una respuesta 200 OK vacía.
- Si el atributo se establece en false, compruebe en la entrada si hay otras directivas cors en el ámbito que son secundarias directas del elemento de entrada y aplíquelas. Si no se encuentra ninguna directiva de cors, termina la solicitud con una respuesta 200 OK vacía.

Cuando la solicitud de GET o HEAD solicitud incluye el encabezado Origin (y, por tanto, se procesa como una solicitud simple entre orígenes) y no coincide con la configuración de la directiva:
- Si el atributo está establecido en true, finalice inmediatamente la solicitud con una respuesta 200 OK vacía.
- Si el atributo está establecido en false, permita que la solicitud continúe normalmente y no agregue ningún encabezado CORS a la respuesta.		 No true

Elementos

Nombre Descripción Necesario Valor predeterminado
allowed-origins Contiene elementos origin que describen los orígenes permitidos para las solicitudes entre dominios. allowed-origins puede contener un único elemento origin que especifica * para permitir cualquier origen, o uno o varios elementos origin que contienen un identificador URI. Sí N/D
allowed-methods Este elemento es necesario si se permiten métodos distintos de GET o POST. Contiene elementos method que especifican los verbos HTTP admitidos. El valor * indica todos los métodos. No Si esta sección no está presente, se admiten GET y POST.
allowed-headers Este elemento contiene elementos header que especifican los nombres de los encabezados que pueden incluirse en la solicitud. Sí N/D
expose-headers Este elemento contiene elementos header que especifican los nombres de los encabezados a los que tendrá acceso el cliente. No N/D

Precaución

Preste atención al usar el carácter comodín * en la configuración de directiva. Esta configuración puede ser excesivamente permisiva y hacer que una API sea más vulnerable a determinadas amenazas de seguridad de API.

elementos allowed-origins

Nombre Descripción Necesario Valor predeterminado
origin El valor puede ser * para permitir todos los orígenes o un identificador URI que especifica un único origen. El URI debe incluir un esquema, un host y un puerto. No incluya las comillas. Sí Si se omite el puerto en un identificador URI, se usa el puerto 80 para HTTP y el puerto 443 para HTTPS.

Atributos de métodos permitidos

Nombre Descripción Necesario Valor predeterminado
preflight-result-max-age El encabezado Access-Control-Max-Age de la respuesta preparatoria se establecerá en el valor de este atributo e influirá en la capacidad del agente del usuario de almacenar en caché la respuesta preparatoria. Se permiten expresiones de directiva. No 0

elementos allowed-methods

Nombre Descripción Necesario Valor predeterminado
method Especifica un verbo HTTP. Se permiten expresiones de directiva. Al menos un elemento method es necesario si la sección allowed-methods está presente. N/D

elementos allowed-headers

Nombre Descripción Necesario Valor predeterminado
header Especifica un nombre de encabezado. Al menos un elemento header es necesario en allowed-headers si la sección está presente. N/D

elementos expose-headers

Nombre Descripción Necesario Valor predeterminado
header Especifica un nombre de encabezado. Al menos un elemento header es necesario en expose-headers si la sección está presente. N/D

Uso

Notas de uso

  • Puede configurar la directiva cors en más de un ámbito (por ejemplo, en el ámbito del producto y en el ámbito global). Asegúrese de que el elemento base está configurado en los ámbitos de operación, API y producto para heredar las directivas necesarias en los ámbitos primarios.
  • Solo la directiva cors se evalúa en la solicitud OPTIONS durante la operaciones preparatorias. Las directivas configuradas restantes se evalúan en la solicitud aprobada.
  • Esta directiva solo se puede usar una vez en una sección de directiva.

Acerca de CORS

CORS es un estándar basado en encabezados HTTP que permite a un explorador y a un servidor interactuar y determinar si se permiten o no solicitudes específicas entre orígenes (llamadas XMLHttpRequest realizadas desde JavaScript en una página web a otros dominios). Esto permite más flexibilidad que si solo se permiten solicitudes del mismo origen, pero es más seguro que permitir todas las solicitudes entre orígenes.

CORS especifica dos tipos de solicitudes entre orígenes:

  • Solicitudes preparatorias El explorador envía primero una solicitud HTTP mediante el método OPTIONS al servidor para determinar si la solicitud real puede enviarse. Si la respuesta del servidor incluye el encabezado Access-Control-Allow-Origin que permite el acceso, el explorador sigue con la solicitud real.

  • Solicitudes sencillas: estas solicitudes incluyen uno o varios encabezados adicionales Origin, pero no desencadenan una solicitud preparatoria de CORS. Solo se permiten las solicitudes que usan los métodos GET y HEAD y un conjunto limitado de encabezados de solicitud.

Escenarios de directiva cors

Configure la directiva cors en API Management para los escenarios siguientes:

  • Habilite la consola de prueba interactiva en el portal para desarrolladores. Consulte la documentación del portal para desarrolladores para obtener detalles.

    Nota

    Al habilitar CORS para la consola interactiva, de forma predeterminada API Management configura la directiva cors en el ámbito global.

  • Habilite API Management responder a solicitudes preparatorias o para pasar a través de solicitudes CORS sencillas cuando los back-end no proporcionan su propia compatibilidad con CORS.

    Nota

    Si la solicitud coincide con una operación con un método OPTIONS definido en la API, no se ejecutará la lógica de procesamiento de solicitudes preparatorias asociada a la directiva cors. Por lo tanto, estas operaciones se pueden usar para implementar una lógica de procesamiento preparatoria personalizada; por ejemplo, para aplicar la directiva cors solo en determinadas condiciones.

Problemas de configuración comunes

  • Clave de suscripción en el encabezado: si configura la directiva cors en el ámbito del producto y la API usa la autenticación de clave de suscripción, la directiva no funcionará cuando se pase la clave de suscripción en un encabezado. Como solución alternativa, modifique las solicitudes para incluir una clave de suscripción como parámetro de consulta.
  • API con control de versiones de encabezado: si configura la directiva cors en el ámbito de la API y la API usa un esquema de control de versiones de encabezado, la directiva no funcionará porque la versión se pasa en un encabezado. Es posible que tenga que configurar un método de control de versiones alternativo, como una ruta de acceso o un parámetro de consulta.
  • Orden de la directiva: puede experimentar un comportamiento inesperado si la directiva cors no es la primera directiva de la sección de entrada. Seleccione Calcular directiva efectiva en el editor de directivas para comprobar el orden de evaluación de directivas en cada ámbito. Por lo general, solo se aplica la primera directiva cors.
  • Respuesta 200 OK vacía: en algunas configuraciones de directiva, ciertas solicitudes entre orígenes se completan con una respuesta vacía 200 OK. Esta respuesta se espera cuando terminate-unmatched-request se establece en su valor predeterminado de true y una solicitud entrante tiene un encabezado Origin que no coincide con un origen permitido configurado en la directiva cors.

Ejemplo

En este ejemplo se muestra cómo admitir solicitudes preparatorias, como aquellas con encabezados o métodos personalizados distintos de GET y POST. Para admitir encabezados personalizados y otros verbos HTTP, use las secciones allowed-methods y allowed-headers tal como se muestra en el ejemplo siguiente.

<cors allow-credentials="true">
    <allowed-origins>
        <!-- Localhost useful for development -->
        <origin>http://localhost:8080/</origin>
        <origin>http://example.com/</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="300">
        <method>GET</method>
        <method>POST</method>
        <method>PATCH</method>
        <method>DELETE</method>
    </allowed-methods>
    <allowed-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
        <header>x-zumo-version</header>
        <header>x-zumo-auth</header>
        <header>content-type</header>
        <header>accept</header>
    </allowed-headers>
    <expose-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
    </expose-headers>
</cors>

Contenido relacionado

Para más información sobre el trabajo con directivas, vea: