Compartir a través de

CORS

  • Artículo

适用于：所有 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 中是必需的。 空值

使用情况

使用注意事项

  • 可以在多个范围（例如，在产品范围和全局范围）配置 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>

后续步骤

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