API security settings enable centralized management of Session Identifiers, Schema Validation Settings, and Token Configurations.
Add a session identifier
Session identifiers are used to identify individual API sessions. ESA collects and analyzes traffic for tagged APIs and generates rate limiting suggestions to help you dynamically adjust your services.
In the ESA console, choose Websites. In the Website column, click the target website.
In the left navigation pane, choose .
On the API Security page, click the Settings tab. In the Session Identifier section, click Add.
Select an identifier type: Header, Cookie, or JWT claims (requires an existing or new claim), and then enter the corresponding name.
Set schema validation
After you upload an API schema, ESA automatically matches it with managed APIs conforming to the schema. ESA validates incoming requests for compliance and processes them according to configured actions.
In the ESA console, choose Websites. In the Website column, click the target site.
In the left navigation pane on the left, choose .
On the API Security page, click the Settings tab. In the Schema Validation Settings section, click Configure.
Configure the settings as required, and then click OK.
Status: Enable or disable the schema validation feature.
Default Action: Select the default action to take on requests that do not comply with the schema. The available actions are:
Uploaded Schemas: The uploaded schema files. ESA automatically parses these files and uses them as API compliance validation rules. For more information, see Schema file specifications.
Add a token
Add JSON Web Token (JWT) information in the Token Configuration section. This information can then be referenced in API Rules for visitor identity verification.
In the ESA console, choose Websites. In the Website column, click the target website.
In the left navigation pane, choose .
On the API Security page, click the Settings tab. In the Token Configuration section, click Add.
Configure the token parameters as required, and then click OK:
Name: Enter a custom name for the token, such as
JWT-Demo.Token Location: Select the location of the token in the request. Choose Header or Cookie and then enter the key.
NoteTo check for tokens in different locations, you can click Or to create a logical
ORcondition. You can check up to four token locations simultaneously.Token Key: Enter a token key manually or upload a JSON file. For more information about key requirements, see Token details.
NoteIf you configure multiple keys, ESA uses the
kidfield to select a key for validation. The request is considered valid if it is validated by any one of the keys.
Schema specifications
File format and size
Format: Schema files must be in
.yml,.yaml, or.jsonformat.Size: The maximum file size is 58 KB. For larger schemas, use the
.jsonformat and compress it before uploading.
Schema content
Version
ESA API security architecture validation currently supports only OpenAPI Specification (OAS) v3.0.x.
Fields
Required fields
openapi: The OAS version string (e.g.,3.0.0).info: Metadata about the API, including aversion(e.g.,1.0.0).paths: The host information where the API is served.servers: The host information where the API is served:url: Only absolute URLs are supported, such ashttps://api.example.com.variables: Server variables are not supported and will be ignored during parsing.
Optional fields
schema: The data structure definition. The following types are supported:int32
uint32
int64
uint64
float
double
boolean
email
reference: Uses$refto point to a predefined object. External and relative references are not supported.requestbody: Defines the request body. Only data with acontent-typeofapplication/jsonis supported.
Example
The following is an example of a .json schema file.{
"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"
}
}
]
}
}
}
}Token details
Token validation is currently available only for JWTs.
Field descriptions
The public key must be in JSON Web Key (JWK) format. The JWK public key must contain the kid and alg fields. The fields are described as follows:
kty: The key type, such asECfor Elliptic Curve.use: The intended use of the public key, such assigfor digital signature.crv: The type of elliptic curve, such asP-256for the NIST standardized P-256 curve.kid: A custom key identifier, such asesa. The JWK must include thekidfield to enable key selection. The JWT claim in the request must also include thekidfield. This field is used for token key rotation.x: The x-coordinate of the elliptic curve public key.y: The y-coordinate of the elliptic curve public key.alg: The algorithm identifier. Currently, onlyES256is supported, which is the ECDSA signature algorithm with SHA-256.
Example
{
"kty": "EC",
"use": "sig",
"crv": "P-256",
"kid": "esa",
"x": "QG3VFVwUX4IatQvBy7sqBvvmticCZ-eX5-nbtGKBOfI",
"y": "A3PXCshn7XcG7Ivvd2K_DerW4LHAlIVKdqhrUnczTD0",
"alg": "ES256"
}