Documentación de Oracle Cloud Infrastructure

Agregación de soporte de CORS a despliegues de API

Descubra cómo utilizar una política de solicitud para agregar soporte de CORS a despliegues de API con gateway de API.

Los exploradores web suelen implementar una "política de mismo origen" para evitar que el código realice solicitudes en un origen distinto del que se usó para distribuir el código. La intención de la política de mismo origen es ofrecer protección frente a sitios web maliciosos. Sin embargo, la política de mismo origen también puede evitar interacciones legítimas entre un servidor y clientes de un origen conocido y de confianza.

El uso compartido de recursos de origen cruzado (CORS) es un estándar de uso compartido de origen cruzado que relaja el nivel de restricción de la política de mismo origen al permitir que el código de una página web consuma una API de REST servida desde un origen diferente. El estándar CORS utiliza cabeceras de solicitud HTTP y cabeceras de respuesta adicionales para especificar los orígenes a los que se puede acceder.

El estándar CORS también necesita que, para determinados métodos de solicitud HTTP, esta sea una comprobación preliminar. Antes de enviar la solicitud real, el explorador web envía una comprobación preliminar al servidor para determinar si se soportan los métodos de la solicitud real. El servidor responde con los métodos que permitirá en una solicitud real. El explorador web solo envía la solicitud real si la respuesta del servidor indica que se permiten los métodos de la solicitud real. El estándar CORS también activa los servidores para notificar a los clientes si las solicitudes pueden incluir credenciales (cookies, cabeceras de autorización o certificados de cliente TLS).

Para obtener más información sobre CORS, consulte los recursos disponibles en línea, incluidos los de W3C y Mozilla.

Mediante el servicio de gateway de API, puede activar el soporte de CORS en las API que despliegue en gateways de API. Al activar el soporte de CORS en un despliegue de API, las solicitudes HTTP previas y las solicitudes reales para el despliegue de API devuelven una o más cabeceras de respuestas de CORS al cliente de API. Los valores de cabecera de respuesta de CORS se definen en la especificación de despliegue de API.

Las políticas de solicitud se utilizan para agregar soporte CORS a las API (consulte Agregación de políticas de solicitud y políticas de respuesta a especificaciones de despliegue de API). Puede aplicar una política de solicitud de CORS de forma global a todas las rutas de una especificación de despliegue de API, o solo a rutas concretas.

Puede agregar una política de solicitud de CORS a una especificación de despliegue de API mediante:

  • uso de la Consola
  • edición de un archivo JSON

Uso de la consola para agregar políticas de solicitud de CORS

Siga estos pasos para agregar una política de solicitud de CORS a una especificación de despliegue de API mediante la consola:

  1. Cree o actualice un despliegue de API con la consola, seleccione la opciónDesde cero e introduzca los detalles en la página Información básica.

    Para obtener más información, consulte Despliegue de una API en un gateway de API a través de la creación de un despliegue de API y Actualización de un gateway de API o un despliegue de API.

  2. En la sección Políticas de solicitud de API de la página Información básica, haga clic en el botón Agregar situado junto a CORS y especifique:

    • Orígenes permitidos: origen que puede acceder al despliegue de API. Por ejemplo, https://oracle.com. Haga clic en + Otro origen para introducir un segundo origen y los orígenes siguientes.
    • Métodos permitidos: uno o varios métodos permitidos en la solicitud real para el despliegue de API. Por ejemplo, GET, PUT.
    • Cabeceras permitidas: opcionalmente, la cabecera HTTP permitida en la solicitud real para el despliegue de API. Por ejemplo, opc-request-id o If-Match. Haga clic en + Otra cabecera para introducir la segunda cabecera y las siguientes.
    • Cabeceras mostradas: de forma opcional, cabecera HTTP a la que pueden acceder clientes de API en la respuesta del despliegue de API a una solicitud real. Por ejemplo, ETag u opc-request-id. Haga clic en + Otra cabecera para introducir la segunda cabecera y las siguientes.
    • Duración máxima en segundos: opcionalmente, valor entero que indica el tiempo (en segundos delta) que un explorador puede almacenar en la caché los resultados de una comprobación preliminar. Si no especifica ningún valor, el valor por defecto es 0.
    • Activar Permitir credenciales: indica si la solicitud real para el despliegue de API se puede hacer mediante credenciales (cookies, cabeceras de autorización o certificados de cliente de TLS). Por defecto, esta opción no está seleccionada.

    Para averiguar cómo se asignan los distintos campos de la política de solicitud de CORS a distintas cabeceras de respuesta de CORS, consulte Cómo se asigna una política de solicitud de CORS a una respuesta de CORS.

  3. Haga clic en Aplicar Cambios.

  4. Haga clic en Siguiente para especificar las opciones de autenticación en la página Autenticación.

    Para obtener más información sobre las opciones de autenticación, consulte Agregación de autenticación y autorización a despliegues de API.

  5. Haga clic en Siguiente para introducir detalles de rutas individuales en el despliegue de API en la página Rutas. Para especificar políticas de solicitud de CORS que se aplican a una ruta individual, haga clic en Mostrar políticas de solicitud de ruta y, a continuación, haga clic en el botón Agregar situado junto a CORS y especifique:

    • Orígenes permitidos: origen que puede acceder a la ruta. Por ejemplo, https://oracle.com. Haga clic en + Otro origen para introducir un segundo origen y los orígenes siguientes.
    • Métodos permitidos: uno o más métodos permitidos en la solicitud real para la ruta. Por ejemplo, GET, PUT.
    • Cabeceras permitidas: opcionalmente, cabecera HTTP que está permitida en la solicitud real para la ruta. Por ejemplo, opc-request-id o If-Match. Haga clic en + Otra cabecera para introducir la segunda cabecera y las siguientes.
    • Cabeceras mostradas: de forma opcional, cabecera HTTP a la que pueden acceder clientes de API en la respuesta del despliegue de API a una solicitud real. Por ejemplo, ETag u opc-request-id. Haga clic en + Otra cabecera para introducir la segunda cabecera y las siguientes.
    • Duración máxima en segundos: opcionalmente, valor entero que indica el tiempo (en segundos delta) que un explorador puede almacenar en la caché los resultados de una comprobación preliminar. Si no especifica ningún valor, el valor por defecto es 0.
    • Activar Permitir credenciales: indica si la solicitud real para la ruta se puede hacer mediante credenciales (cookies, cabeceras de autorización o certificados de cliente de TLS). Por defecto, esta opción no está seleccionada.

    Para averiguar cómo se asignan los distintos campos de la política de solicitud de CORS a distintas cabeceras de respuesta de CORS, consulte Cómo se asigna una política de solicitud de CORS a una respuesta de CORS.

  6. Haga clic en Aplicar cambios y, a continuación, haga clic en Siguiente para revisar los detalles introducidos para el despliegue de API y para las rutas individuales.
  7. Haga clic en Crear o en Guardar cambios para crear o actualizar el despliegue de API.
  8. (Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.

Edición de un Archivo JSON para agregar políticas de solicitud de CORS

Siga estos pasos para agregar una política de solicitud de CORS a una especificación de despliegue de API en un archivo JSON:

  1. Con el editor de JSON de su elección, modifique la especificación de despliegue de API existente a la que desea agregar soporte de CORS o cree una nueva especificación de despliegue de API (consulte Creación de una especificación de despliegue de API).

    Por ejemplo, la siguiente especificación de despliegue de API básico define una función sencilla de Hello World sin servidor en OCI Functions como un único backend:

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

  2. Para especificar una política de solicitud de CORS que se aplica globalmente a todas las rutas de un despliegue de API:

    1. Inserte una sección requestPolicies antes de la sección routes si no existe ninguna. Por ejemplo:

      {
  "requestPolicies": {},
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

    2. Agregue la siguiente política cors a la nueva sección requestPolicies para aplicarla de forma global a todas las rutas de un despliegue de API:

      {
  "requestPolicies": {
    "cors":{
      "allowedOrigins": [<list-of-origins>],
      "allowedMethods": [<list-of-methods>],
      "allowedHeaders": [<list-of-implicit-headers>],
      "exposedHeaders": [<list-of-exposed-headers>],
      "isAllowCredentialsEnabled": <true|false>,
      "maxAgeInSeconds": <seconds>
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

      donde:

      • "allowedOrigins": [<list-of-origins>] es una lista necesaria de orígenes separados por comas que pueden acceder al despliegue de API. Por ejemplo, , "allowedOrigins": ["*", "https://oracle.com"].
      • "allowedMethods": [<list-of-methods>] es una lista opcional separada por comas de los métodos HTTP que se permiten en la solicitud real para el despliegue de API. Por ejemplo, "allowedMethods": ["*", "GET"].
      • "allowedHeaders": [<list-of-implicit-headers>] es una lista opcional separada por comas de cabeceras HTTP que se permiten en la solicitud real para el despliegue de API. Por ejemplo, "allowedHeaders": ["opc-request-id", "If-Match"].
      • "exposedHeaders": [<list-of-exposed-headers>] es una lista opcional separada por comas de cabeceras HTTP a las que pueden acceder los clientes de API en la respuesta del despliegue de API a una solicitud real. Por ejemplo, "exposedHeaders": ["ETag", "opc-request-id"]
      • "isAllowCredentialsEnabled": <true|false> es true o false. Indica si la solicitud real para el despliegue de API se puede realizar mediante credenciales (cookies, cabeceras de autorización o certificados de cliente TLS). Si no se especifica, el valor por defecto es false.
      • "maxAgeInSeconds": <seconds> es un valor entero que indica el tiempo (en segundos delta) que un explorador puede almacenar en la caché los resultados de una comprobación preliminar. Si no se especifica, el valor por defecto es 0.

      Por ejemplo:

      {
  "requestPolicies": {
    "cors":{
      "allowedOrigins": ["*", "https://oracle.com"],
      "allowedMethods": ["*", "GET"],
      "allowedHeaders": [],
      "exposedHeaders": [],
      "isAllowCredentialsEnabled": false,
      "maxAgeInSeconds": 3000
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

      Para averiguar cómo se asignan los distintos campos de la política de solicitud de CORS a distintas cabeceras de respuesta de CORS, consulte Cómo se asigna una política de solicitud de CORS a una respuesta de CORS.

  3. Para especificar una política de solicitud de CORS que se aplica a una ruta individual:

    1. Inserte una sección requestPolicies después de la sección de backend para la ruta a la que desea aplicar la política. Por ejemplo:

      {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {}
    }
  ]
}
    2. Agregue la siguiente política cors a la nueva sección requestPolicies para aplicarla solo a esta ruta concreta:
      {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "cors":{
           "allowedOrigins": [<list-of-origins>],
           "allowedMethods": [<list-of-methods>],
           "allowedHeaders": [<list-of-implicit-headers>],
           "exposedHeaders": [<list-of-exposed-headers>],
           "isAllowCredentialsEnabled": <true|false>,
           "maxAgeInSeconds": <seconds>
        }
      }
    }
  ]
}

      donde:

      • "allowedOrigins": [<list-of-origins>] es una lista necesaria de orígenes separados por comas que pueden acceder al despliegue de API. Por ejemplo, , "allowedOrigins": ["*", "https://oracle.com"].
      • "allowedMethods": [<list-of-methods>] es una lista opcional separada por comas de los métodos HTTP que se permiten en la solicitud real para el despliegue de API. Por ejemplo, "allowedMethods": ["*", "GET"].
      • "allowedHeaders": [<list-of-implicit-headers>] es una lista opcional separada por comas de cabeceras HTTP que se permiten en la solicitud real para el despliegue de API. Por ejemplo, "allowedHeaders": ["opc-request-id", "If-Match"].
      • "exposedHeaders": [<list-of-exposed-headers>] es una lista opcional separada por comas de cabeceras HTTP a las que pueden acceder los clientes de API en la respuesta del despliegue de API a una solicitud real. Por ejemplo, "exposedHeaders": ["ETag", "opc-request-id"]
      • "isAllowCredentialsEnabled": <true|false> es true o false. Indica si la solicitud real para el despliegue de API se puede realizar mediante credenciales (cookies, cabeceras de autorización o certificados de cliente TLS). Si no se especifica, el valor por defecto es false.
      • "maxAgeInSeconds": <seconds> es un valor entero que indica el tiempo (en segundos delta) que un explorador puede almacenar en la caché los resultados de una comprobación preliminar. Si no se especifica, el valor por defecto es 0.

      Por ejemplo:

      {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "cors":{
           "allowedOrigins": ["*", "https://oracle.com"],
           "allowedMethods": ["*", "GET"],
           "allowedHeaders": [],
           "exposedHeaders": [],
           "isAllowCredentialsEnabled": false,
           "maxAgeInSeconds": 3000
        }
      }
    }
  ]
}

      Para averiguar cómo se asignan los distintos campos de la política de solicitud de CORS a distintas cabeceras de respuesta de CORS, consulte Cómo se asigna una política de solicitud de CORS a una respuesta de CORS.

  4. Guarde el archivo JSON que contiene la especificación de despliegue de API.

  5. Utilice la especificación de despliegue de API al crear o actualizar un despliegue de API de las siguientes formas:

    • Especificando el archivo JSON en la consola al seleccionar la opción Cargar API existente.
    • Especificando el archivo JSON en una solicitud para la API REST de gateway de API.

    Para obtener más información, consulte Despliegue de una API en un gateway de API a través de la creación de un despliegue de API y Actualización de un gateway de API o un despliegue de API.

  6. (Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.

Cómo se asigna una política de solicitud de CORS a una respuesta de CORS

Los diferentes campos de una política de solicitud de CORS se asignan a distintas cabeceras de respuesta de CORS, como se muestra en la tabla:

Campo Se asigna a la cabecera de respuesta de CORS Incluido en respuesta a la comprobación preliminar Incluido en respuesta a la solicitud real Notas
allowed Origins Access-Control-Allow-Origin Sí Sí

¿Es necesario?: Sí

Tipo de datos: cadena[]

Valor por defecto: N/A

Se utiliza para devolver una lista separada por comas de orígenes que pueden acceder al despliegue de API.

La especificación de CORS solo permite un origen. Por lo tanto, en caso de que haya varios orígenes, el origen de cliente se debe comprobar dinámicamente con respecto a la lista de valores permitidos. Se permiten los valores"*" y "null".
allowed Methods Access-Control-Allow-Methods Sí No

¿Es necesario?: No

Tipo de datos: cadena[]

Valor por defecto: lista vacía

Se utiliza para devolver una lista separada por comas de métodos HTTP que se permiten en la solicitud real para el despliegue de API.

El valor por defecto de Access-Control-Allow-Methods es permitir a través de todos los métodos sencillos, incluso en las comprobaciones preliminares.
allowed Headers Access-Control-Allow-Headers Sí No

¿Es necesario?: No

Tipo de datos: cadena[]

Valor por defecto: lista vacía

Se utiliza para devolver una lista separada por comas de cabeceras HTTP que se permiten en la solicitud real para el despliegue de API.

exposed Headers Access-Control-Expose-Headers No Sí

¿Es necesario?: No

Tipo de datos: cadena[]

Valor por defecto: lista vacía

Se utiliza para devolver una lista separada por comas de cabeceras HTTP a las que los clientes pueden acceder en la respuesta del despliegue de API para una solicitud real. Esta lista de cabeceras HTTP es una adición a las cabeceras de respuesta con protección de CORS.
isAllow Credentials Enabled Access-Control-Allow-Credentials Sí Sí

¿Es necesario?: No

Tipo de datos: booleano

Por defecto: false

Se utiliza para devolver true o false. Indica si la solicitud real para el despliegue de API se puede realizar mediante credenciales (cookies, cabeceras de autorización o certificados de cliente TLS).

Para permitir que se realicen solicitudes con credenciales, defina isAllowCredentialsEnabled en true.
maxAge InSeconds Access-Control-Max-Age Sí No ¿Es necesario?: No

Tipo de datos: entero

Por defecto: 0

Se utiliza para indicar el tiempo (en segundos delta) que un explorador puede almacenar en la caché los resultados de una comprobación preliminar. Se ignora si se define en 0.