API安全相關內容設定 - Edge Security Acceleration

通過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"
}