Política de CORS

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

ícono de política

Qué

El uso compartido de recursos entre dominios (CORS) es un mecanismo estándar que permite que las llamadas XMLHttpRequest (XHR) de JavaScript que se ejecutan en una página web interactúen con recursos de dominios que no son de origen, CORS es una solución implementada con frecuencia en la política del mismo origen que aplican todos los navegadores.

Por ejemplo, si realizas una llamada XHR a la API de Twitter desde el código JavaScript que se ejecuta en el navegador, la llamada fallará. Esto se debe a que el dominio que entrega la página a tu navegador no es el mismo dominio que entrega la API de Twitter. CORS proporciona una solución a este problema, ya que permite que los servidores lo habiliten si desean proporcionar uso compartido de recursos entre dominios.

Esta política de CORS permite a los clientes de Apigee establecer políticas de CORS para las APIs consumidas por las aplicaciones web.

Esta es una política estándar y se puede implementar en cualquier tipo de entorno. No todos los usuarios necesitan conocer los tipos de políticas y el entorno. Para obtener información sobre los tipos de políticas y la disponibilidad con cada tipo de entorno, consulta Tipos de políticas.

Elemento <CORS>

Define la política de CORS.

Valor predeterminado Consulta la pestaña Política predeterminada, a continuación
¿Es obligatorio? Obligatorio
Tipo Objeto complejo
Elemento principal N/A
Elementos secundarios <AllowCredentials>
<AllowHeaders>
<AllowMethods>
<AllowOrigins>
<DisplayName>
<ExposeHeaders>
<GeneratePreflightResponse>
<IgnoreUnresolvedVariables>
<MaxAge>

El elemento <CORS> usa la siguiente sintaxis:

Sintaxis

El elemento <CORS> usa la siguiente sintaxis:


<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <DisplayName>DISPLAY_NAME</DisplayName>
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowMethods>[GET, PUT, POST, DELETE, ...|*]</AllowMethods>
  <AllowHeaders>[origin, x-requested-with, accept, content-type, ...]</AllowHeaders>
  <ExposeHeaders>[X-CUSTOM-HEADER-A, X-CUSTOM-HEADER-B, ... | *]</ExposeHeaders>
  <MaxAge>[integer|-1]</MaxAge>
  <AllowCredentials>[false|true]</AllowCredentials>
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</CORS>

Política predeterminada

En el siguiente ejemplo, se muestra la configuración predeterminada cuando agregas la política de CORS a tu flujo en la IU de Edge:

<CORS continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <AllowOrigins>{request.header.origin}</AllowOrigins>
    <AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
    <AllowHeaders>origin, x-requested-with, accept, content-type</AllowHeaders>
    <ExposeHeaders>*</ExposeHeaders>
    <MaxAge>3628800</MaxAge>
    <AllowCredentials>false</AllowCredentials>
    <GeneratePreflightResponse>true</GeneratePreflightResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS>

Cuando insertas una nueva política de CORS en la IU de Apigee, la plantilla contiene stubs para todas las operaciones posibles. Por lo general, debes seleccionar qué operaciones quieres realizar con esta política y quitar el resto de los elementos secundarios. Por ejemplo, si deseas especificar los métodos HTTP permitidos para acceder al recurso, usa el elemento <AllowMethods> y quita los otros elementos secundarios de la política para que sea más legible.

Este elemento tiene los siguientes atributos que son comunes a todas las políticas:

Atributo Predeterminada (obligatorio) Descripción
name N/A Obligatorio

El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres.

De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

continueOnError falso Opcional Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta:
enabled true Opcional Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará, incluso si permanece conectada a un flujo.
async   falso Obsoleta Este atributo dejó de estar disponible.

Cada uno de estos elementos secundarios se describe en las siguientes secciones.

Ejemplos

En las siguientes secciones, se proporcionan ejemplos de todos los elementos secundarios.

Referencia del elemento secundario

En esta sección, se describen los elementos secundarios de <CORS>.

<AllowCredentials>

Indica si el emisor puede enviar la solicitud real (no la solicitud preliminar) mediante credenciales. Se traduce al encabezado Access-Control-Allow-Credentials.

Valor predeterminado Si no se especifica, no se establecerá Access-Control-Allow-Credentials.
¿Es obligatorio? Opcional
Tipo Booleano
Elemento principal <CORS>
Elementos secundarios Ninguna

El elemento <AllowCredentials> usa la siguiente sintaxis:

Sintaxis

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowCredentials>[false|true]</AllowCredentials>
</CORS>
      

Ejemplo

En este ejemplo, se establece el encabezado Access-Control-Allow-Credentials como false. Es decir, el emisor no puede enviar la solicitud real (no la solicitud preliminar) mediante credenciales.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowCredentials>false</AllowCredentials>
</CORS>

<AllowHeaders>

Lista de los encabezados HTTP que se pueden usar cuando se solicita el recurso. Serializado en el encabezado Access-Control-Allow-Headers.

Valor predeterminado Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers
¿Es obligatorio? Opcional
Tipo String, con plantilla de mensaje* compatible
Elemento principal <CORS>
Elementos secundarios Ninguna

* Para obtener más información, consulta ¿Qué es una plantilla de mensaje?

El elemento <AllowHeaders> usa la siguiente sintaxis:

Sintaxis

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowHeaders>[origin, x-requested-with, accept, content-type, ...]</AllowHeaders>
</CORS>

Ejemplo

CORS AllowOrigins example

This example specifies the HTTP headers that can be used when requesting the resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowHeaders>origin, x-requested-with, accept, content-type</AllowHeaders>
</CORS>

<AllowMethods>

Lista de los métodos HTTP permitidos para acceder al recurso. El contenido se serializará en el encabezado Access-Control-Allow-Methods.

Valor predeterminado GET, POST, HEAD, OPTIONS
¿Es obligatorio? Opcional
Tipo String, con plantilla de mensaje* compatible
Elemento principal <CORS>
Elementos secundarios Ninguna

* Para obtener más información, consulta ¿Qué es una plantilla de mensaje?

El elemento <AllowMethods> usa la siguiente sintaxis:

Sintaxis

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowMethods>[GET, PUT, POST, DELETE, ...|*]</AllowMethods>
</CORS>

Ejemplo:
Lista

En este ejemplo, se especifican los métodos HTTP que pueden acceder al recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
</CORS>

Ejemplo:
Comodín

En este ejemplo, se especifica que todos los métodos HTTP pueden acceder al recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowMethods>*</AllowMethods>
</CORS>

<AllowOrigins>

Una lista de orígenes que tienen acceso al recurso. Usa un asterisco (*) para habilitar el acceso a un recurso desde cualquier origen. De lo contrario, proporciona una lista de orígenes permitidos separados por comas. Si se encuentra una coincidencia, el Access-Control-Allow-Origin saliente se configura en el origen según lo que proporciona el cliente.

Valor predeterminado N/A
¿Es obligatorio? Obligatorio
Tipo String, con plantilla de mensaje* compatible
Elemento principal <CORS>
Elementos secundarios Ninguna

* Para obtener más información, consulta ¿Qué es una plantilla de mensaje?

El elemento <AllowOrigins> usa la siguiente sintaxis:

Sintaxis

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
</CORS>

Ejemplo:
URL única

En este ejemplo, se especifica un único origen de URL que puede acceder al recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>https://www.w3.org</AllowOrigins>
</CORS>

Ejemplo:
Varias URL

En este ejemplo, se especifican varios orígenes que pueden acceder al recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>https://www.w3.org, https://www.apache.org</AllowOrigins>
</CORS>

Ejemplo:
Variable de contexto

En este ejemplo, se especifica una variable de contexto que representa uno o más orígenes que pueden acceder al recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{origins.list}</AllowOrigins>
</CORS>

Ejemplo:
Variable de flujo

En este ejemplo, se especifica una variable de flujo que representa un origen que puede acceder al recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
</CORS>

Ejemplo:
Comodín

En este ejemplo, se especifica que todos los orígenes pueden acceder al recurso.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>*</AllowOrigins>
</CORS>

<DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

El elemento <DisplayName> es común a todas las políticas.

Valor predeterminado N/A
¿Es obligatorio? Opcional. Si omites <DisplayName>, se usa el valor del atributo name de la política.
Tipo String
Elemento principal <PolicyElement>
Elementos secundarios Ninguna

El elemento <DisplayName> usa la siguiente sintaxis:

Sintaxis

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Ejemplo

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

El elemento <DisplayName> no tiene atributos ni elementos secundarios.

<ExposeHeaders>

Una lista de encabezados HTTP a los que los navegadores pueden acceder o un asterisco (*) para permitir todos los encabezados HTTP. Serializado en el encabezado Access-Control-Expose-Headers.

Valor predeterminado Si no se especifica, no se establecerá Access-Control-Expose-Headers. Los encabezados no simples no se exponen de forma predeterminada.
¿Es obligatorio? Opcional
Tipo String, con plantilla de mensaje* compatible
Elemento principal <CORS>
Elementos secundarios Ninguna

* Para obtener más información, consulta ¿Qué es una plantilla de mensaje?

El elemento <ExposeHeaders> usa la siguiente sintaxis:

Sintaxis

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <ExposeHeaders>[X-CUSTOM-HEADER-A, X-CUSTOM-HEADER-B, ... | *]</ExposeHeaders>
</CORS>

Ejemplo

En este ejemplo, se especifica que los navegadores pueden acceder a todos los encabezados HTTP.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <ExposeHeaders>*</ExposeHeaders>
</CORS>

<GeneratePreflightResponse>

Indica si la política debe generar y mostrar la respuesta de solicitud preliminar de CORS. Si es false, no se envía ninguna respuesta. En su lugar, se propagan las siguientes variables de flujo:

  • cross_origin_resource_sharing.allow.credentials
  • cross_origin_resource_sharing.allow.headers
  • cross_origin_resource_sharing.allow.methods
  • cross_origin_resource_sharing.allow.origin
  • cross_origin_resource_sharing.allow.origins.list
  • cross_origin_resource_sharing.expose.headers
  • cross_origin_resource_sharing.max.age
  • cross_origin_resource_sharing.preflight.accepted
  • cross_origin_resource_sharing.request.headers
  • cross_origin_resource_sharing.request.method
  • cross_origin_resource_sharing.request.origin
  • cross_origin_resource_sharing.request.type
Valor predeterminado true
¿Es obligatorio? Opcional
Tipo Booleano
Elemento principal <CORS>
Elementos secundarios Ninguna

El elemento <GeneratePreflightResponse> usa la siguiente sintaxis:

Sintaxis

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
</CORS>

Ejemplo

En este ejemplo, se especifica que la política debe generar y mostrar la respuesta de solicitud preliminar de CORS.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <GeneratePreflightResponse>true</GeneratePreflightResponse>
</CORS>

<IgnoreUnresolvedVariables>

Determina si el procesamiento se detiene cuando se encuentra una variable sin resolver. Configúralo como true para ignorar las variables sin resolver y continuar con el procesamiento, de lo contrario, false.

Valor predeterminado true
¿Es obligatorio? Opcional
Tipo Booleano
Elemento principal <CORS>
Elementos secundarios Ninguna

El elemento <IgnoreUnresolvedVariables> usa la siguiente sintaxis:

Sintaxis

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</CORS>

Ejemplo

En este ejemplo, se especifica que el procesamiento continúa cuando se encuentra una variable sin resolver.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS>

<MaxAge>

Especifica cuánto tiempo se pueden almacenar en caché los resultados de una solicitud preliminar en segundos. Un valor de -1 propaga el encabezado Access-Control-Max-Age con un valor de -1, que inhabilita el almacenamiento en caché, lo que requiere una verificación de solicitud preliminar OPTIONS para todas las llamadas. Esto se define en la especificación Access-Control-Max-Age.

Valor predeterminado 1800
¿Es obligatorio? Opcional
Tipo Entero
Elemento principal <CORS>
Elementos secundarios Ninguna

El elemento <MaxAge> usa la siguiente sintaxis:

Sintaxis

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <MaxAge>[integer|-1]</MaxAge>
</CORS>

Ejemplo:
Caché

En este ejemplo, se especifica que los resultados de una solicitud de solicitud preliminar se pueden almacenar en caché durante 3628800 segundos.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <MaxAge>3628800</MaxAge>
</CORS>

Ejemplo:
Sin caché

En este ejemplo, se especifica que los resultados de una solicitud de solicitud preliminar no se pueden almacenar en caché.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <MaxAge>-1</MaxAge>
</CORS>

Notas de uso

Solicitudes OPTIONS

Cuando se recibe y procesa una solicitud OPTIONS mediante la política de CORS, la ejecución del flujo del proxy se transfiere directamente al flujo previo de respuesta del proxy. Se omite el flujo de solicitud por completo y continúa la ejecución desde allí. No es necesario crear una condición para ignorar la solicitud de OPTIONS en el flujo de solicitud de proxy.

En las llamadas posteriores, cuando la política de CORS se ejecuta, si el MaxAge establecido en la política no venció, el flujo continúa con normalidad. Durante el flujo de respuesta final justo antes de “Respuesta enviada al cliente”, un paso de ejecución especial de CORS “CORSResponseOrErrorFlowExecution” establece encabezados de respuesta CORS (Access-Control-Allow-Credentials, Access-Control-Allow-Origin y Access-Control-Expose-Headers) para mostrar una respuesta validada por CORS.

Códigos de error

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Soluciona fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla Estado de HTTP Causa
steps.cors.UnresolvedVariable 500 Este error se produce si una variable especificada en la política CORS es una de las siguientes:
  • Está fuera del alcance (no está disponible en el flujo específico en el que se ejecuta la política) o
  • o

  • No se puede resolver (no está definida)

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Nombre del error Causa
InvalidMaxAge MaxAge no es un número
MissingAllowOrigins AllowOrigins no se especificó
InvalidHTTPMethods Uno de los métodos de AllowMethods no es válido
AllowHeadersSizeTooLarge El tamaño de la string en AllowHeaders es demasiado grande.
ExposeHeadersSizeTooLarge El tamaño de la string en ExposeHeaders es demasiado grande.

Variables con fallas

Estas variables se configuran cuando esta política activa un error en el entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables Donde Ejemplo
fault.name = "FAULT_NAME" FAULT_NAME es el nombre de la falla, como se indica en la tabla Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. fault.name Matches "UnresolveVariable"
cors.POLICY_NAME.failed POLICY_NAME es el nombre especificado por el usuario de la política que generó la falla. cors.AddCORS.failed = true

Ejemplo de respuesta de error

{
   "fault":{
      "detail":{
         "errorcode":"steps.cors.UnresolvedVariable"
      },
      "faultstring":"CORS[AddCORS]: unable to resolve variable wrong.var"
   }
}

Ejemplo de regla de falla

<FaultRule name="Add CORS Fault">
    <Step>
        <Name>Add-CORSCustomUnresolvedVariableErrorResponse</Name>
        <Condition>(fault.name Matches "UnresolvedVariable") </Condition>
    </Step>
    <Condition>(cors.Add-CORS.failed = true) </Condition>
</FaultRule>

Variables de flujo

Se agregará el objeto CorsFlowInfo FlowInfo y estará disponible para realizar un seguimiento.

Propiedad Tipo Lectura/escritura Descripción El permiso comienza
cross_origin_resource_sharing.allow.credentials Booleano Lectura/escritura Valor desde <AllowCredentials> Solicitud de proxy
cross_origin_resource_sharing.allow.headers String Lectura/escritura Valor desde <AllowHeaders> Solicitud de proxy
cross_origin_resource_sharing.allow.methods String Lectura/escritura Valor desde <AllowMethods> Solicitud de proxy
cross_origin_resource_sharing.allow.origin String Lectura/escritura El origen de la solicitud permitido; vacío si no está en la lista de anunciantes permitidos Solicitud de proxy
cross_origin_resource_sharing.allow.origins.list String Lectura/escritura Valor desde <AllowOrigins> Solicitud de proxy
cross_origin_resource_sharing.expose.headers String Lectura/escritura Valor desde <ExposeHeaders> Solicitud de proxy
cross_origin_resource_sharing.max.age Número entero Lectura/escritura Valor desde <MaxAge> Solicitud de proxy
cross_origin_resource_sharing.preflight.accepted Booleano Lectura/escritura Indica si se acepta la solicitud preliminar Solicitud de proxy
cross_origin_resource_sharing.request.headers String Lectura/escritura El valor del encabezado Access-Control-Request-Headers de la solicitud Solicitud de proxy
cross_origin_resource_sharing.request.method String Lectura/escritura El valor del encabezado Access-Control-Request-Method de la solicitud Solicitud de proxy
cross_origin_resource_sharing.request.origin String Lectura/escritura Es igual a request.header.origin Solicitud de proxy
cross_origin_resource_sharing.request.type String Lectura/escritura

Tipo de solicitud de CORS. Valores posibles:

  • REAL: Una solicitud que no es una solicitud de comprobación previa
  • PRE_flight: Una solicitud de comprobación previa
Solicitud de proxy