CORS

项目
08/19/2024

适用于：所有 API 管理层级

cors 策略向操作或 API 添加跨源资源共享 (CORS) 支持，以便从基于浏览器的客户端执行跨域调用。

提示

为了帮助你配置此策略，门户提供了基于窗体的引导式编辑器。详细了解如何设置或编辑 API 管理策略。

策略语句

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

属性

客户	说明	需要	默认
allow-credentials	预检响应中的 `Access-Control-Allow-Credentials` 标头将设置为此属性的值，会影响客户端在跨域请求中提交凭据的功能。允许使用策略表达式。	否	`false`
terminate-unmatched-request	控制与策略设置不匹配的跨源请求的处理。允许使用策略表达式。当 `OPTIONS` 请求作为预检请求处理并且 `Origin` 标头与策略设置不匹配时： - 如果该属性设置为 `true`，则立即以空的 `200 OK` 响应终止请求 - 如果该属性设置为 `false`，请检查入站内容中是否有作为入站元素直接子项的其他范围内 `cors` 策略并应用它们。如果未找到 `cors` 策略，则终止请求并返回空的 `200 OK` 响应。当 `GET` 或 `HEAD` 请求包含 `Origin` 标头（因此被作为简单的跨域请求处理）并且与策略设置不匹配时： - 如果该属性设置为 `true`，则立即以空的 `200 OK` 响应终止请求。 - 如果该属性设置为 `false`，则允许请求正常进行，但不将 CORS 标头添加到响应中。	否	`true`

元素

名称	说明	需要	默认
allowed-origins	包含的 `origin` 元素说明了跨域请求的允许来源。 `allowed-origins` 可能包含单个 `origin` 元素，该元素指定允许任何源的 `*`，或者包含一个或多个内含 URI 的 `origin` 元素。	是	空值
allowed-methods	如果允许 `GET` 或 `POST` 之外的方法，则此元素是必需的。包含 `method` 元素，用于指定支持的 HTTP 谓词。值 `*` 指示所有方法。	否	如果此部分不存在，则 `GET` 和 `POST` 受支持。
allowed-headers	此元素包含 `header` 元素，用于指定可以包括在请求中的标头的名称。	是	不适用
expose-headers	此元素包含 `header` 元素，用于指定可以通过客户端访问的标头的名称。	否	不适用

注意

在策略设置中谨慎使用通配符 *。此配置可能过于宽松，并且可能会使 API 更容易受到某些 API 安全威胁的影响。

allowed-origins 元素

名称	说明	需要	默认
origin	值可以是允许所有源的 `*`，或者是用于指定单个源的 URI。 URI 必须包括方案、主机和端口。不要包含引号。	是	如果 URI 中省略了端口，则端口 80 用于 HTTP，端口 443 用于 HTTPS。

allowed-methods 属性

名称	说明	需要	默认
preflight-result-max-age	预检响应中的 `Access-Control-Max-Age` 标头将设置为此属性的值，并且会影响用户代理缓存预检响应的功能。允许使用策略表达式。	否	0

allowed-methods 元素

名称	说明	需要	默认
method	指定 HTTP 谓词。允许使用策略表达式。	如果 `allowed-methods` 部分存在，则至少一个 `method` 元素是必需。	不适用

allowed-headers 元素

名称	说明	需要	默认
标头	指定标头名称。	如果该部分存在，则至少一个 `header` 元素在 `allowed-headers` 中是必需的。	空值

expose-headers 元素

名称	说明	需要	默认
标头	指定标头名称。	如果该部分存在，则至少一个 `header` 元素在 `expose-headers` 中是必需的。	空值

使用情况

策略节：入站
策略范围：全局、工作区、产品、API、操作
网关：经典、消耗、自承载

使用注意事项

可以在多个范围（例如，在产品范围和全局范围）配置 cors 策略。确保在操作、API 和产品范围配置 base 元素，以继承父范围所需的策略。
在预检期间只会对 OPTIONS 请求评估 cors 策略。剩余的已配置策略将针对已批准的请求进行评估。

此策略只能在策略部分中使用一次。

关于 CORS

CORS 是一种基于 HTTP 标头的标准，该标准允许浏览器与服务器交互，并确定是否允许特定的跨源请求（通过某个网页上的 JavaScript 对其他域执行的 XMLHttpRequest 调用）。与只允许同源请求相比，它的灵活性更高，而且比允许所有跨源请求更安全。

CORS 指定两种类型的跨源请求：

预检的（或“预检”）请求 - 浏览器首先使用 OPTIONS 方法向服务器发送 HTTP 请求，以确定是否允许发送实际请求。如果服务器响应包含 Access-Control-Allow-Origin 标头以允许进行访问，浏览器接下来将发送实际请求。
简单请求 - 这些请求包含一个或多个额外的 Origin 标头，但不触发 CORS 预检。只会允许那些使用 GET 和 HEAD 方法以及一组有限的请求标头的请求。

`cors` 策略场景

为以下场景配置 API 管理中的 cors 策略：

在开发人员门户中启用交互式测试控制台。有关详细信息，请参阅开发人员门户文档。

注意

为交互式控制台启用 CORS 时，默认情况下，API 管理在全局范围内配置 cors 策略。
启用 API 管理，以回复预检请求或在后端不提供自己的 CORS 支持时传递简单的 CORS 请求。

注意

如果请求与具有 API 中定义的 OPTIONS 方法的操作匹配，则不会执行与 cors 策略关联的预检请求处理逻辑。因此，此类操作可用于实现自定义预检处理逻辑，例如，仅在某些条件下应用 cors 策略。

常见配置问题

标头中的订阅密钥 - 如果在产品范围内配置 cors 策略，并且 API 使用订阅密钥身份验证，则当订阅密钥在标头中传递时，该策略将不起作用。解决方法是，修改请求以包含订阅密钥作为查询参数。
使用标头版本控制的 API - 如果在 API 范围内配置 cors 策略，并且 API 使用标头版本控制方案，则该策略将不起作用，因为版本会传入标头中。可能需要配置一个替代版本控制方法，例如路径或查询参数。
策略顺序 - 如果 cors 策略不是入站部分中的第一个策略，则可能会遇到意外行为。在策略编辑器中选择“计算有效策略”，以在每个范围检查策略评估顺序。通常，只会应用第一个 cors 策略。
空的“200 正常”响应 - 在某些策略配置中，在某些跨源请求完成时会返回空的 200 OK 响应。当 terminate-unmatched-request 设置为其默认值 true 并且传入请求的 Origin 标头与 cors 策略中配置的允许源不匹配时，该响应是预期的响应。

示例

此示例演示如何支持预检请求，例如那些具有自定义标头或 GET 和 POST 之外的方法的预检请求。若要支持自定义标头和其他 HTTP 谓词，请使用 allowed-methods 和 allowed-headers 部分，如以下示例所示。

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

跨域

后续步骤

有关使用策略的详细信息，请参阅：

教程：转换和保护 API
策略参考，其中提供了策略语句及其设置的完整列表
策略表达式
设置或编辑策略
策略示例

通过