You need to enable JavaScript to run this app.
导航
远程鉴权
最近更新时间:2024.09.23 10:45:26首次发布时间:2022.08.31 21:50:42

本文档介绍火山引擎内容分发网络(CDN)提供的远程鉴权功能。

远程鉴权概述

如果您的站点有专属的鉴权服务器对用户请求进行鉴权,您可以在 CDN 中配置远程鉴权。

远程鉴权的流程如下:

  1. 用户向您的站点发送请求。请求中包含鉴权参数。
  2. 在收到用户请求后,CDN 将用户请求转发到鉴权服务器。
  3. 鉴权服务器对用户请求进行鉴权,并将鉴权结果返回给 CDN。
  4. CDN 根据鉴权结果,将用户请求的内容发送给用户或者拒绝用户请求。

远程鉴权与 URL 鉴权的区别

URL 鉴权:CDN 直接对请求进行鉴权。

远程鉴权:CDN 不对请求进行鉴权,而是转发请求并从鉴权服务器接收鉴权结果。

功能优先级

CDN 提供的一系列访问控制功能有不同的优先级。在 CDN 处理用户请求时,这些功能按优先级对请求生效。参见 访问控制功能的优先级

操作步骤

  1. 登录 火山引擎内容分发网络控制台

  2. 在左侧导航栏,点击 域名管理

  3. 域名管理 页面,找到需要配置的域名,点击 管理

  4. 在域名页面上,点击 访问控制 页签。

  5. 在页面右上方,点击 编辑配置

  6. 远程鉴权 下方,设置 状态 为启用。

  7. 配置以下标签页上的设置。

  8. 配置完成后,在页面右上方,点击 提交编辑

生效对象

在该标签页上,您可以添加一个或者多个规则。您最多可以添加 50 个规则。当 CDN 收到一个用户请求时,会根据规则的出现顺序依次将规则与请求相匹配。如果一个规则匹配了请求,该请求就会进入远程鉴权的流程。

说明

如果您需要对所有请求进行鉴权,可以添加一条规则并指定以下配置:

  • 设置 规则类型目录匹配
  • 设置 规则/

配置说明

配置说明

规则类型

规则的匹配条件。CDN 将匹配的请求发送到鉴权服务器进行认证。该配置有以下选项:

  • 文件后缀:表示规则用于匹配指定扩展名的文件的请求。

  • 目录匹配:表示规则用于匹配指定目录下文件的请求。

  • 文件全路径:表示规则用于匹配指定文件的请求。

是否匹配

指定匹配的方式。该配置的选项如下:

  • 匹配:表示匹配规则内容的请求需要被鉴权。

  • 不匹配:表示不匹配规则内容的请求需要被鉴权。

需要留意的是,如果您添加了多条规则,这些规则需要设置为相同的匹配方式。

规则

表示规则的内容,长度不能超过 1,024 个字符,不能包含以下字符:

  • 连续斜杠(//)、空格、美元符号($)、问号(?)、Delete(ASCII code 127)。

同时,

  • 如果规则类型是 文件后缀,规则内容必须是一个或者多个以分号(;)分隔的文件后缀。文件后缀无需以句点(.)开头。例如:png;txt

  • 如果规则类型是 文件目录,规则内容必须是一个或者多个以分号(;)分隔的目录路径。目录路径必须以斜杠(/)开头和结尾。例如:/chs/foods/;/us/birds/

  • 如果规则类型是 文件全路径,规则内容必须是一个或者多个以分号(;)分隔的文件路径。文件路径必须以斜杠(/)开头,可以包含星号(*)用来表示一个或者多个字符。例如:/chs/foods/local*sets;/us/birds/chickadee

鉴权请求地址

在该标签页上,您指定鉴权服务器的配置。

配置说明

配置说明示例

远程鉴权地址(主)

表示鉴权服务器的主地址,长度不能超过 100 个字符。主地址必须采用以下格式之一:

  • <scheme>://<domain>

  • <scheme>://<ip>

<scheme> 的值是 http 或者 https。<domain> 的值不能是 localhost。<ip> 的值不能是 127.0.0.1

https://example.com

远程鉴权地址(备)表示鉴权服务器的备地址,长度不能超过 100 个字符,格式和输入要求与主地址相同。

请求路径

表示鉴权 URL 中的路径。鉴权服务器的地址和该路径组成了鉴权 URL。CDN 会把用户请求转发到该鉴权 URL。该配置的选项如下:

  • 遵循用户请求路径:表示鉴权 URL 中的路径与用户请求 URL 中的路径相同。

  • 指定具体请求路径:表示一个指定的路径。您需要在 鉴权路径 中指定该路径。

鉴权路径

如果 请求路径指定具体请求路径,该配置才会出现。在该配置中,您指定一个鉴权路径。鉴权路径必须以斜杠(/)开头,长度不能超过 100 个字符。鉴权路径可以包含除了以下字符的可打印 ASCII 字符:

  • 连续的斜杠(//)、百分号(%)、美元符号($)、空格、问号(?)、Delete(ASCII code 127)。

/sign

请求方法

表示在发送鉴权请求时,CDN 所使用的请求方法。该配置的选项如下:

  • 跟随用户请求的方法:表示鉴权请求使用的方法与用户请求相同。

  • GET:表示鉴权请求使用 GET 方法。

  • POST:表示鉴权请求使用 POST方法。

  • HEAD:表示鉴权请求使用 HEAD 方法。

鉴权请求参数

在该标签页上,您指定鉴权请求需要包含的参数。

alt

配置说明

配置说明

用户请求参数

表示哪些用户请求 URL 中的查询参数包含在鉴权请求中。该配置有以下选项:

  • 保留全部参数:表示鉴权请求包括用户请求 URL 中的所有查询参数。

  • 删除全部参数:表示鉴权请求不包括用户请求 URL 中的任何查询参数。

  • 保留部分参数:表示鉴权请求包括用户请求 URL 中的指定的查询参数。

参数清单

如果 用户请求参数保留部分参数,该配置才会出现。该配置表示用户请求 URL 中的哪些查询参数需要包括在鉴权请求中。多个参数用分号 (;) 分隔,总长度不能超过 1,024 个字符。参数名称是大小写敏感的,可以包含除了以下字符以外的可打印 ASCII 字符:

  • 空格、双引号(")、Delete(ASCII code 127)
添加鉴权请求参数该配置表示您需要额外添加的查询参数。您最多可以添加 50 个参数。

请求参数名称

表示您需要添加的一个查询参数的名称。参数名称不能超过 1,024 个字符,可以包含除了以下字符的可打印 ASCII 字符:

  • 双引号(")、空格、Delete(ASCII code 127)

取值方式

表示该查询参数的值是如何定义的。该配置有以下选项:

  • 常量:表示该参数值是一个固定值,类型是字符串。

  • 变量:表示该参数的值来自一个变量。参见 变量说明

参数取值

表示该查询参数的值。该配置的说明如下:

  • 如果 取值方式常量,您指定一个固定值作为该参数的值,长度不能超过 1,024 个字符。该参数值不能以美元符号($)开头,可以包含除了以下字符的可打印 ASCII 字符:

    • 双引号(")、Delete(ASCII code 127)
  • 如果 取值方式变量,您需要从列表中选择一个变量。您选择的变量的值会作为该参数的值。

变量说明

CDN 提供了以下变量。

变量说明示例
host表示用户请求中 Host 头的值。example.com:8080
ua表示用户请求中 User-Agent 头的值。Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail
referer表示用户请求中 Referer 头的值。https://www.example.com/file?name=123
content_type表示用户请求中 Content-Type 头的值。text/html
X-Forwarded-For表示用户请求中 X-Forwarded-For 头的值。20.5.118.10
client_ip表示发送用户请求的 IP 地址。15.15.15.10
scheme表示用户请求使用的协议。https
server_protocol表示用户请求使用的协议的版本。HTTP/2.0
URI表示用户请求中的 URL,不包含查询字符串。/dir/page.php
req_args表示用户请求中所有的查询参数。color=red&n=10
request_method表示用户请求使用的请求方法。GET
request_uri表示用户请求中的 URL,包含查询字符串。/dir/page.php?color=red&n=10
local_ip表示在 CDN 中,响应用户请求的边缘节点的 IP 地址。267.89.0.45
req_time表示 CDN 收到用户请求的时间。关于时间格式,请参见示例。18/Apr/2022:16:48:48 +0800
msec表示当前的时间。格式是十进制的 Unix 时间戳。1650558396

鉴权请求头

在该标签页上,您指定鉴权请求需要包含的请求头。

配置说明

配置说明

HOST 请求头

表示鉴权请求中 HOST 头部的值。该配置有以下选项:

  • 加速域名:表示 HOST 头部的值与加速域名相同。

  • 自定义:表示一个指定的 HOST 头部值。如果您选择该选项,页面会出现 自定义请求 HOST 配置。在该配置中,您需要输入一个 HOST 头部的值,长度不能超过 1,024 个字符。

用户其他请求头

表示哪些用户请求中的请求头包含在鉴权请求中。该配置有以下选项:

  • 保留全部头部:表示鉴权请求包含用户请求中的所有请求头。

  • 删除全部头部:表示鉴权请求不包含任何用户请求中请求头。

  • 保留部分头部:表示鉴权请求包含用户请求中的指定请求头。

头部清单如果 用户请求头保留部分头部,该配置才会出现。该配置指定需要包含在鉴权请求中的请求头。多个请求头用分号 (;) 分隔。请求头是大小写不敏感的。
添加鉴权请求头该配置表示您需要额外添加的请求头。您最多可以添加 50 个请求头。

请求头部名称

表示一个您需要添加的请求头。请求头是大小写不敏感的,不能是 Host,长度不能超过 1,024 个字符。该请求头可以包含除了以下字符以外的可打印 ASCII 字符:

  • 下划线(_)、空格、双引号("),Delete(ASCII code 127)

取值方式

表示该请求头的值是如何定义的。该配置有以下选项:

  • 常量:表示该请求头的值是一个固定值,类型是字符串。

  • 变量:表示该请求头的值来自一个变量。参见 变量字段说明

参数取值

表示该请求头的值。该配置的说明如下:

  • 如果 取值方式常量,您指定一个固定值作为该请求头的值。该值的长度不能超过 1,024 个字符,不能以美元符号($)开头,可以包含除了以下字符以外的可打印 ASCII 字符:

    • 双引号(")、Delete(ASCII code 127)。
  • 如果 取值方式变量,您需要从列表中选择一个变量。您选择的变量的值会作为该请求头的值。

鉴权结果

在该标签页上,您指定 CDN 是如何处理鉴权服务器返回的鉴权结果的。

在截图所展示的配置中,缓存key 中指定的字段是 URIclient_ip。该配置表示 CDN 基于用户请求的以下属性对鉴权结果进行缓存:

  • 请求来自的 IP 地址
  • 请求的 URL

注意

在您设置缓存key 时, URL 字段是必须包含的,不然 CDN 无法判断鉴权结果所对应的请求文件。

这样,之后对于来自相同 IP 地址的请求,如果请求 URL 是相同的,CDN 会使用缓存的鉴权结果。

配置说明

配置说明

鉴权成功状态码

表示从鉴权服务器返回的状态码中,哪些被认为是鉴权成功。默认值是 200。

您可以输入范围在 200-299 中的一个或者多个状态码。多个状态码使用分号(;)分隔。您也可以输入 2xx 表示 200-299 范围中的任意一个状态码。

鉴权失败状态码

表示从鉴权服务器返回的状态码中,哪些被认为是鉴权失败。默认值是 401。

您可以输入范围在 400-499 中的一个或者多个状态码。多个状态码使用分号(;)分隔。您也可以输入 4xx 表示 400-499 范围中的任意一个状态码。

其他状态码

该配置表示在满足以下所有条件时,CDN 对用户请求的处理方式。

  • 鉴权服务器返回的状态码不是您指定的表示鉴权成功的状态码。

  • 鉴权服务器返回的状态码不是您指定的表示鉴权失败的状态码。

该配置有以下选项:

  • 默认放行:表示 CDN 认为用户请求鉴权成功,并将请求的文件返回给用户。

  • 默认拦截:表示 CDN 认为用户请求鉴权失败,拒绝该用户请求。

鉴权结果缓存

表示 CDN 是否缓存鉴权结果,也就是鉴权服务器返回的鉴权状态码。您可以设置该配置为 开启 或者 关闭。默认是 关闭

在开启该配置后,对于收到的用户请求,CDN 会检测该请求的鉴权状态码是否已被缓存。如果鉴权状态码已被缓存,CDN 则使用该鉴权状态码来确定是否将请求的文件发送给用户。

该配置可以提升 CDN 响应用户请求的效率。

缓存时间表示鉴权状态码的缓存时间,单位是秒。该配置仅在 鉴权结果缓存开启 的情况下才出现。您可以输入范围在 1-86400 之间的一个值。86,400 秒表示 24 小时。

缓存key

表示缓存的鉴权状态码中所包含的字段。这些字段是您在该配置中定义的。每个鉴权状态码都有一个唯一的缓存key。该配置仅在 鉴权结果缓存开启 的情况下才出现。

同时,CDN 通过缓存key 来判断用户请求是否命中了鉴权状态码的缓存。 当收到一个请求时,CDN 尝试使用请求中的字段来匹配缓存key。如果找到了匹配,CDN 就会使用该缓存的鉴权状态码。

注意

缓存key 中必须包含 URL 这个字段,不然 CDN 无法判断鉴权结果所对应的请求文件。

响应客户端拦截状态码

表示鉴权失败时,CDN 响应用户请求的状态码。默认的状态码是 403。

您可以输入范围在 400-499 中的任意一个状态码。

鉴权超时时间表示鉴权请求的超时时间,单位是毫秒,默认值是 200。您可以输入的超时时间的范围是 200-3600。

异常执行策略

该配置表示鉴权异常发生时,CDN 处理用户请求的方式。

该配置有以下选项:

  • 默认放行:表示 CDN 认为用户请求鉴权成功,并将请求的文件返回给用户。

  • 默认拦截:表示 CDN 认为用户请求鉴权失败,拒绝该用户请求。

鉴权异常包括,但不限于,以下情况:

  • 鉴权请求超时。

  • 鉴权服务器拒绝了鉴权请求。

  • CDN 无法与鉴权服务器建立连接。