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-椭圆曲线密钥、RSA-RSA密钥。
use：公钥用途，如 sig - 用于数字签名。
crv：椭圆曲线类型，仅适用于椭圆曲线（EC）密钥，如 P-256 - NIST标准化的P-256椭圆曲线。
kid：自定义的密钥标识符，如esa。JWK必须带有kid字段，用于密钥的选择；同样的，请求的JWT的声明中也必须带有kid字段。使用该字段可用于令牌密钥的轮换。
x：使用椭圆曲线密钥时，椭圆曲线公钥的x坐标。
y：使用椭圆曲线密钥时，椭圆曲线公钥的y坐标。
alg：算法标识，当前支持： RS256 - RSA with SHA-256签名算法。
n：RSA密钥的模数（modulus），仅适用于RSA密钥。
e：RSA密钥的公共指数（public exponent），仅适用于RSA密钥。

示例

以下为RSA密钥的JWK示例。使用RSA密钥时，crv、x、y字段应为空串。

{
  "kty": "RSA",  
  "kid": "test-rsa-key",
  "alg": "RS256",
  "use": "sig",
  "n": "wR8LJDq2pM1uPD5KfmMaasmV20nwgVYnDlsxRjmryLStQeqW-3fe-ELV1tlYHq2-hl8HNNxz5eud8olmqxtrgpihPN9c_pbLY-Jc04_tdpWs10ms1vgoz0S11JEVCK6q9EJ_QCTAxO6GBCdI9t0oUTpBz6QuQCIJAOQdW2k7gZr8CmCn_ianTU1nTxBzAoBxO_r32kl7lx9RTFCZHBJsm8twJ7o0ZXpUjbjhOY2LgdDx3t09YDDOMDYzEOZ86NVzm8qXSekBJFf5-FGNe0Lkht1lsMlBnqlfmWz8q5zUkPZ6XslpgyVqqSaw4DGxXV8aGWRFcOB0Ac2bush6McBAhQ",
  "e": "AQAB",
  "crv": "",
  "x": "",
  "y": ""
}