API Security

• Validate JSON Web Tokens (JWT).
• Define valid payloads for API requests through one or more API schema(s).
• A request violates your API Security configuration when it satisfies one of the following conditions:
  • JWT validation is enabled and Edgio is unable to verify the JWT.
  • The payload violates at least one requirement defined within your API schema.
• Discover the APIs that have been requested in the last 30 days by reviewing the API Discovery section of the API Security page.
• Review violations of your API Security configuration through the WAF Events view of the Security dashboard.

Setup #

1. Create an API Security ruleset. An API Security ruleset consists of the following components:
   • API Security Rules: Define one or more API Security rules that allow you to:
     • Validate request bodies through an API schema.
     • Validate RS256-signed JWTs through a JSON Web Key Set (JWKS).
     • Define the conditions under which the JWT and request body validation defined within this rule will be enforced.
   • API Schema: An API schema is a JSON schema that describes the structure for a valid API payload.
   An API Security rule requires at least one JWKS or API schema.
2. Assign an API Security rule to a Security Application configuration and define the enforcement action that will be applied to requests that contain an invalid JWT or violate the API schema(s) defined in the previous step.

API Security Rule #

• Relative Path(s): You may restrict payload inspection to one or more relative path(s). This relative path starts directly after the hostname. The available comparison modes are listed below.
  • Default: Edgio Security will inspect all POST, PUT, and PATCH requests to ensure that they satisfy the API schema.
  • Exact match (multiple entries): Restrict inspection to specific relative path(s).
  • Wildcard match: Restrict inspection to a wildcard pattern for the relative path.
  • Regex match: Restrict inspection to a regular expression for the relative path.
  Wildcard and regular expression match comparison modes require Security Premier, Business, or Essentials. Contact your account manager or our sales department at 1 (866) 200 - 5463 to upgrade your account.
• Method(s): You may restrict payload inspection to one or more of the following HTTP method(s): PUT | POST | PATCH

Exact Match (Multiple Entries) #

Wildcard Match #

• *: Matches zero or more characters.

  Sample Configuration	Matches	Does Not Match
  cat*	cat category muscat	cAt Category

• ?: Matches a single character.

  Sample Configuration	Matches	Does Not Match
  cat?	cats muscats	Cats cat

• [abc]: Matches a single character defined within the brackets.

  Sample Configuration	Matches	Does Not Match
  [cm]art	cart mart	tart start

• [a-z]: Matches a single character from the specified range.

  Sample Configuration	Matches	Does Not Match
  [a-z]art	cart mart tart	Cart marT start

• [!abc]: Matches a single character that is not defined within the brackets.

  Sample Configuration	Matches	Does Not Match
  [!cm]art	Cart Mart tart	cart mart tArt

• [!a-z]: Matches a single character that is excluded from the specified range.

  Sample Configuration	Matches	Does Not Match
  [!a-m]art	Cart Mart tart	cart mart tArt

Regex Match #

JSON Web Tokens (JWT) #

• Be defined within the Authorization request header using the following syntax:
  Authorization: Bearer <TOKEN>
• Contain the following components:
  • iss: An iss value identifies the issuer of the JWT.
  • kid: A kid value identifies the key through which the JWT was signed.

• Contain up to 2 JWKs.
• Each JWK must be signed by a known provider using the RS256 algorithm. Self-signed certificates are disallowed since we cannot verify the chain of authority.
• A JWK must contain x5c and x5t parameters through which we can verify that the key was signed by a known provider.
• A JWK must exclude private key parameters, such as p, q, dp, dq, and qi.

1{
2    "keys": [{
3            "kty": "RSA",
4            "use": "sig",
5            "kid": "174EFCA3923B25163F581A0CB71CAD97B036E0B8",
6            "x5t": "F078o5I7JRY_WBoMtxytl7A24Lg",
7            "x5c": [
8                "MIIEWzCCA0OgAwIBAgIJAPzw5pQEyIL4MA0GCSqGSIbgZ3
9                ...
10                fIwQFTXJNGSzbYy8tBGSZI22rYtkz2rvVXTGFNX2HglofS0v"
11            ],
12            "e": "AQAB",
13            "n": "n1x3isqbPYjG2dUm5d5N1MBk9zKHt5LujgFXJO1SCnCW
14                  ...
15                  kGzKbQXk8QoXonkB9waAUJl8DZWmyR4oHhLw4UySKCow",
16            "alg": "RS256"
17        }, {
18            "kty": "RSA",
19            "use": "sig",
20            "kid": "635BCE35DAAADA6B1C4F31DBBE9D610A296CAA2E",
21            "x5t": "Y1vONdqq2mscTzHbvp1hCilsqi4",
22            "e": "AQAB",
23            "n": "59_PSn8HTeKK6s7e9eZxmXxjVE-YwBxRuEONekpOX0tlSYf3
24                  ...
25                  f6iGFKt6Rxwmcl0KB3Mc_0AmT6GMhbR-KCx29KFNHtgn92Zw",
26            "x5c": [
27                "MIIG3DCCBcSgpM1FpkyeMiuHqpM1FpkyeMiuHq512512dqg
28                 ...
29                 f8OPsg5XMNTSZJUZrUULTCfl7jJeVBibqlXyeckjEG/MzM="
30            ],
31            "alg": "RS256"
32        }
33    ]
34}

API Schema #

JSON Schema Syntax #

• Edgio does not consider a number with a zero fractional part (e.g., 1.0, or 42.0) an integer.
• Edgio ignores the $schema keyword.
• Specify exclusiveMaximum and exclusiveMinimum as integers.
• Remote schemas are unsupported.
• String formats introduced after draft 4 are unsupported. For example, the following formats are unsupported: time | date | duration | idn-email
• The following keywords are unsupported: $anchor | $comment | $dynamicAnchor | $dynamicRef | $recursiveRef |const | contentEncoding | contentMediaType| contentSchema | dependentRequired | if-then-else | minContains | maxContains | prefixItems | propertyNames | unevaluated

JSON Schema Examples #

• String Example: The following sample schema requires an API request to only contain a single string value:
  JSON

  Copy

  1{
  2    "api_gw_id": "mnriXoB6",
  3    "type": "string"
  4}

• Object Examples: The following sample schema requires an API request to contain an object. This object must contain a property called email set to a properly formatted email address:
  JSON

  Copy

  1{
  2    "api_gw_id": "mnriXoB6",
  3    "type": "object",
  4    "properties": {
  5    	"email": {
  6            "type": "string",
  7        	"format": "email"
  8    	}
  9	},
  10    "required": ["email"]
  11}

  The following sample schema requires an API request to contain an object. This object must contain a property called price set to a number greater than 0. If this object contains latitude, longitude, or id, then the validation defined for those properties will be enforced. For example, latitude may only be set to -90, 90, or any number in between that range.
  JSON

  Copy

  1{
  2    "api_gw_id": "fg3r67doc1",
  3    "type": "object",
  4    "properties": {
  5        "latitude": {
  6            "type": "number",
  7            "minimum": -90,
  8            "maximum": 90
  9        },
  10        "longitude": {
  11            "type": "number",
  12            "minimum": -180,
  13            "maximum": 180
  14        },
  15        "id": {
  16            "type": "integer",
  17            "minimum": 0,
  18            "maximum": 999,
  19            "exclusiveMaximum": false
  20        },
  21        "price": {
  22            "type": "number",
  23            "minimum": 0,
  24            "exclusiveMinimum": true
  25        }
  26    },
  27    "required": ["price"]
  28}

API Security Ruleset Administration #

• Administer API Security rulesets from the API Security page.
• Apply an API Security ruleset to production traffic by adding it to a Security Application configuration and then determining how it will be enforced. Multiple Security Application configurations may use the same API Security ruleset.
• An API Security rule requires at least one JWKS or API schema.
• It may take up to 2 minutes for an update to an API Security ruleset to be applied across our entire network.

1. Navigate to the API Security page.
   1. From the Edgio Console, select the desired organization.
   2. From the Security section, click API Security.
2. Click + Create New API Rule.
3. In the Name of Ruleset option, type the unique name by which this API Security ruleset will be identified. This name should be sufficiently descriptive to identify it when setting up a Security Application configuration.
4. Add a JSON schema that defines the structure for a valid API payload.
   1. In the Name option, type a name for this JSON schema.
   2. Perform one of the following steps:
      • Autogenerate Schema: Perform the following steps to automatically generate a JSON schema from a sample payload:
        1. Click Derive Schema from Example.
        2. Paste a sample JSON payload.
        3. Click Next >. Edgio will generate an API schema that describes the basic structure for your sample JSON payload.
        4. Optional. Enhance this API schema. For example, you may define a range of valid values for integer properties or you may define certain properties as required.
        5. When finished, click Apply.
      • Upload Schema: Upload an API schema by clicking Upload Schema JSON, selecting the desired file, and then clicking Open.
      • Manual Entry: Type or paste the desired API schema.
   3. Click Save Schema.
   4. Add another JSON schema by clicking + Create New from within the Schemas section and then repeating steps 4.1 - 4.4.
   You may apply different API schemas to different endpoints or operations by creating an API Security rule for each API schema. You should then restrict each API Security rule to only apply API schema validation to the desired set of endpoints or operations.
5. Add an API Security rule that identifies a JSON schema created in the previous step and the set of requests to which it will be applied.
   1. Below the Schemas section, click + Create New.
   2. In the Name option, type a name for this API Security rule.
   3. Optional. Restrict the set of requests that will be inspected to one or more specific relative path(s).
      1. From the URL Path(s) option, determine whether Edgio will perform URL path comparisons by exact match, regular expression, or wildcards.
      2. Specify the desired relative path or regular expression.
         If you selected Exact Match, then you may specify multiple relative paths. Press ENTER after typing each desired URL path.
   4. Optional. Restrict the set of requests that will be inspected by HTTP method by selecting the desired HTTP method from the Methods option. Repeat this step as needed.
   5. Optional. Validate JWTs included within an API request’s Authorization header.
      1. Enable the JWT Validation option.
      2. Define a JSON Web Key Set (JWKS) by performing either of the following steps:
         • Upload a JWKS by clicking Upload JWKS, selecting the desired file, and then clicking Open.
         • Paste the desired JWKS within the JWKS option.
      3. By default, API requests must include a valid JWT. Enable the Allow Empty Tokens option to allow requests without an Authorization header.
   6. Optional. Require requests to provide a valid API payload. From the Schema option, select the JSON schema created in step 4.
   7. Click Save.

1. Navigate to the API Security page.
   1. From the Edgio Console, select the desired organization.
   2. From the Security section, click API Security.
2. Click on the desired API Security ruleset.
3. Make the desired changes.
4. Click Save.

1. Check your Security Application configurations to verify that the desired API Security ruleset is not in use.
2. Navigate to the API Security page.
   1. From the Edgio Console, select the desired organization.
   2. From the Security section, click API Security.
3. Click on the desired API Security ruleset.
4. Click Delete.
5. Click Confirm.

API Discovery #

• Expand an endpoint to break down request statistics by HTTP method and status code.
• Request statistics are rounded to whole numbers. This may cause some entries to display 100% or 0% even though there are multiple entries for that endpoint.
• Use this information to discover legacy or deprecated endpoints that are still being requested.

Version Control #

• View a previous version of a configuration.
• Reactivate a previous version of a configuration.
• Compare a previous version of a configuration to the current version.

1. Load the desired security configuration (e.g., access rule, rate rule, or custom rule).
2. Click Versions.

   

3. Click on the desired version to view it.

   

4. Optional. Compare the version selected in the previous step to the current version by clicking Diff. Differences between those two versions are highlighted in green (new or updated lines) and red (modified or deleted lines).
5. Optional. Reactivate the version selected in step 3 by clicking Reactivate. Click Reactivate this version to confirm that it will be reactivated.