API安全相关内容设置-边缘安全加速(ESA)-阿里云帮助中心

通过API安全设置，可以对会话标识符、架构验证设置、令牌配置进行统一管理。

添加会话标识符

会话标识符可用于标识API的各个会话。ESA将采集并分析被标记API的流量，为对应API生成限频建议，帮助您动态调节业务。

在ESA控制台，选择站点管理，在站点列单击目标站点。
在左侧导航栏，选择安全防护 > API安全。
在API安全页面，选择设置页签，单击会话标识符栏的添加按钮进行配置。
根据业务需求，选择标识符类型：标头、Cookie或JWT声明（需要已创建或新建），并填入对应的自定义标头名称即可。

设置架构验证

上传API的架构标准后，ESA将自动匹配符合该规范的已管理API，同时针对传入的请求进行合规验证并进行处理。您可以在架构验证设置中管理功能开启与否、配置默认执行动作以及上传自定义架构文件。

在ESA控制台，选择站点管理，在站点列单击目标站点。
在左侧导航栏，选择安全防护 > API安全。
在API安全页面，选择设置页签，单击架构验证设置栏的配置按钮进行配置。
根据业务需求进行配置后，单击确认即可：
- 状态：通过该入口配置是否启用架构验证功能。
- 默认执行动作：选择要对架构的不合规请求执行的默认操作。可选的动作包含：
  - 拦截：阻止不合规的请求，并记录拦截日志，可通过事件分析查看详情。
  - 观察：放行不合规的请求，并记录日志，可通过事件分析查看详情。
  - 无：不进行任何操作。
- 已上传的架构：上传自定义的架构文件，ESA将自动进行解析，作为API合规验证规则，具体可参考架构文件说明。

添加令牌

在令牌配置中添加令牌JWT（JSON Web Token）相关信息，即可在API规则中引用，用于访问者的身份验证。

在ESA控制台，选择站点管理，在站点列单击目标站点。
在左侧导航栏，选择安全防护 > API安全。
在API安全页面，选择设置页签，单击令牌配置栏的添加按钮进行配置。
按业务需求完成令牌参数填写后，单击确定即可。
- 配置名称：输入您自定义的令牌名称，如JWT-Demo。
- 令牌位置：选择令牌在请求中的位置，可选择标头和Cookie两种字段，并输入对应的键值。
  说明
  为适配不同业务中JWT的所在位置，通过单击Or可以创建逻辑或条件，可同时判断最多4个令牌位置。
- 令牌密钥：通过手动输入或上传JSON文件来添加令牌密钥，密钥要求可参考令牌说明。
  说明
  若配置多个密钥，则会根据kid字段选取密钥进行校验，若有一份密钥校验通过则通过。

架构文件说明

类型和大小

架构验证文件仅支持 .yml、.yaml 或 .json 格式，最大上传大小为 58KB。如果上传架构文件过大，可以使用.json格式并且在本地进行压缩。

架构内容

版本

ESA API安全架构验证当前仅支持OAS v3.0.x版本。

字段

必选字段

openapi：API版本信息，如3.0.0。
info：架构文件说明，如“version”：“1.0.0”。
paths：至少包含一个API路径，如/api
servers：Host信息。支持以下子字段：
- url：仅支持绝对URL，如https://api.example.com。
- variables：ESA不支持服务器变量，解析时将忽略变量占位符。

可选字段

schema：数据结构定义，支持以下类型：
- int32
- uint32
- int64
- uint64
- float
- double
- boolean
- email
reference：使用$ref指向预定义对象，不支持外部和相对引用。
requestbody：定义请求体，仅支持content-type为 application/json 类型数据。

示例

以 .json 格式文件为例。

{
    "openapi": "3.0.0",
    "info": {
        "title": "example",
        "description": "example",
        "version": "1.0"
    },
    "servers": [
    {
      "url": "https://example1.aliyun.com",
      "description": "example1 url"
    },
    {
      "url": "https://example2.aliyun.com",
      "description": "example2 url"
    }
    ],
    "components": {
        "schemas": {
            "ParamsObject": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "value": {
                        "type": "string"
                    }
                },
                "required": [
                    "id",
                    "value"
                ]
            }
        }
    },
    "paths": {
        "/example/{param1}": {
            "get": {
                "operationId": "getexampleById",
                "parameters": [
                    {
                        "name": "param1",
                        "in": "path",
                        "required": true,
                        "description": "id",
                        "schema": {
                            "type": "integer",
                            "format": "int32"
                        }
                    }
                ]
            }
        },
        "/api1": {
            "post": {
                "operationId": "post_api1",
                "summary": "post api1 request",
                "parameters": [],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ParamsObject"
                            }
                        }
                    }
                }
            },
            "get" :{
                "operationId": "get_api1",
                "summary": "get api1 request",
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "format": "int32"
                        }
                    },
                    {
                        "name": "name",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        }
    }
}

令牌说明

当前令牌校验仅用于JWT验证。

字段说明

公钥格式仅支持JWK，且JWT公钥必须含有kid和alg字段。字段含义可参考：

kty：密钥类型，如 EC-椭圆曲线密钥。
use：公钥用途，如 sig - 用于数字签名。
crv：椭圆曲线类型，如 P-256 - NIST标准化的P-256椭圆曲线
kid：自定义的密钥标识符，如esa。JWK必须带有kid字段，用于密钥的选择；同样的，请求的JWT的声明中也必须带有kid字段。使用该字段可用于令牌密钥的轮换。
x：使用椭圆曲线密钥时，椭圆曲线公钥的x坐标。
y：使用椭圆曲线密钥时，椭圆曲线公钥的y坐标。
alg：算法标识，当前支持： ES256 - ECDSA with SHA-256签名算法。

示例

{
  "kty": "EC",
  "use": "sig",
  "crv": "P-256",
  "kid": "esa",
  "x": "QG3VFVwUX4IatQvBy7sqBvvmticCZ-eX5-nbtGKBOfI",
  "y": "A3PXCshn7XcG7Ivvd2K_DerW4LHAlIVKdqhrUnczTD0",
  "alg": "ES256"
}