Política de CORS

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

Consulta la documentación de Apigee Edge.

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. Para obtener información sobre los tipos de políticas y la disponibilidad con cada tipo de entorno, consulta Tipos de políticas.

Precaución:

La implementación de una política de CORS puede disminuir la rigurosidad de la política del mismo origen (SOP). Si un desarrollador de proxy configura el encabezado Access-Control-Allow-Origin para permitir todo (*), inhabilita efectivamente la protección del mismo origen.

El campo AllowOrigins es un elemento de política obligatorio y el valor predeterminado no debe configurarse para permitir todos (*). Los desarrolladores de políticas deben tomar decisiones cuidadosas antes de exponer sus recursos.

Casos de uso

Un caso de uso común de CORS es la función Prueba esta API del portal de desarrolladores.

Si deseas obtener más información, consulta Configura tu proxy de API para que admita el panel Probar esta API.

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: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual
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	Ninguno

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 tiene permiso para enviar la solicitud real (no la solicitud preliminar) usando 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	Ninguno

* 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

En este ejemplo, se especifican los encabezados HTTP que se pueden usar cuando se solicita el recurso.

<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	Ninguno

* 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	Ninguno

* 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.

Nota: También puedes establecer una variable de contexto en una plantilla de mensaje como un asterisco (*).

Precaución: Si un desarrollador de proxy configura el encabezado Access-Control-Allow-Origin para permitir todo (*), inhabilita eficazmente la protección del mismo origen. El valor predeterminado no debe configurarse para permitir todos (*). Los desarrolladores de políticas deben tomar decisiones cuidadosas antes de exponer sus recursos.

<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	Ninguno

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	Ninguno

* 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	Ninguno

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	Ninguno

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	Ninguno

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.

Nota : Si <GeneratePreflightResponse> se establece como verdadero y se produce un error, la política muestra una respuesta al cliente de inmediato y se omite el flujo de error. Las siguientes variables no se propagan:

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

Nota: Para controlar errores, se recomienda capturar la parte de código de la respuesta de error. No dependas del texto en la string con errores, ya que podría cambiar.

{
   "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