diff --git a/src/content/docs/api-shield/api-gateway.mdx b/src/content/docs/api-shield/api-gateway.mdx index 603ea3f8d1e0050..3498e62641b371e 100644 --- a/src/content/docs/api-shield/api-gateway.mdx +++ b/src/content/docs/api-shield/api-gateway.mdx @@ -9,7 +9,7 @@ sidebar: API Gateway is a package of features that will do everything for your APIs, including: -- **Security**: Protect your API from malicious traffic with [API Discovery](/api-shield/security/api-discovery/), [Schema Validation](/api-shield/security/schema-validation/), [mTLS validation](/api-shield/security/mtls/), and more. +- **Security**: Protect your API from malicious traffic with [API Discovery](/api-shield/security/api-discovery/), [Schema validation](/api-shield/security/schema-validation/), [mTLS validation](/api-shield/security/mtls/), and more. - **Management and monitoring**: Streamline API management with [Endpoint Management](/api-shield/management-and-monitoring/) and [tools](https://blog.cloudflare.com/api-gateway/) like analytics, routing, and authentication. - **Logging, quota management, and more**: All of Cloudflare's [established features](https://blog.cloudflare.com/api-gateway/), like caching, load balancing, and log integrations work natively with API Gateway. diff --git a/src/content/docs/api-shield/frequently-asked-questions.mdx b/src/content/docs/api-shield/frequently-asked-questions.mdx index a51c69cb34a5ba6..3ecf2201e4866df 100644 --- a/src/content/docs/api-shield/frequently-asked-questions.mdx +++ b/src/content/docs/api-shield/frequently-asked-questions.mdx @@ -59,7 +59,7 @@ Not currently. ## What version of OpenAPI specification do you support? -The importing ([Schema Validation](/api-shield/security/schema-validation/)) and exporting ([Schema Learning](/api-shield/management-and-monitoring/#endpoint-schema-learning)) of OpenAPI schemas from our product to customers is done using **OpenAPI v3.0**. Any specifications using patched versions (3.0.x) are compatible as well. +The importing ([Schema validation](/api-shield/security/schema-validation/)) and exporting ([Schema Learning](/api-shield/management-and-monitoring/#endpoint-schema-learning)) of OpenAPI schemas from our product to customers is done using **OpenAPI v3.0**. Any specifications using patched versions (3.0.x) are compatible as well. --- diff --git a/src/content/docs/api-shield/get-started.mdx b/src/content/docs/api-shield/get-started.mdx index 0d972352825b3fb..f43f691d45ea8fd 100644 --- a/src/content/docs/api-shield/get-started.mdx +++ b/src/content/docs/api-shield/get-started.mdx @@ -26,15 +26,15 @@ Enabling API Shield features will have no impact on your traffic until you choos -## Upload a schema using Schema Validation (optional) +## Upload a schema using Schema validation (optional) -Schema Validation protects your APIs by ensuring only requests matching your API schema are allowed to communicate with your origin. +Schema validation protects your APIs by ensuring only requests matching your API schema are allowed to communicate with your origin. -While not strictly required, uploading a pre-existing schema will offer the chance to automatically add endpoints to Endpoint Management. If you already have a schema, you can upload it to [Schema Validation](/api-shield/security/schema-validation/). +While not strictly required, uploading a pre-existing schema will offer the chance to automatically add endpoints to Endpoint Management. If you already have a schema, you can upload it to [Schema validation](/api-shield/security/schema-validation/). :::note -It is recommended to start with Schema Validation rules set to `log` to review logged requests in **Security** > **Events**. When you are confident that only the correct requests are logged, you should switch the rule to `block`. +It is recommended to start with Schema validation rules set to `log` to review logged requests in **Security** > **Events**. When you are confident that only the correct requests are logged, you should switch the rule to `block`. ::: If you do not have a schema to upload, continue reading this guide to learn how to generate a schema with API Shield. @@ -56,10 +56,10 @@ Cloudflare’s machine learning models have already inspected your existing traf :::note -Schema Validation, Schema Learning, JWT Validation, Sequence Analytics, Sequence Mitigation, and rate limit recommendations only run on endpoints saved to Endpoint Management. +Schema validation, Schema Learning, JWT validation, Sequence Analytics, Sequence Mitigation, and rate limit recommendations only run on endpoints saved to Endpoint Management. ::: -You can save your endpoints directly from [API Discovery](/api-shield/management-and-monitoring/#add-endpoints-from-api-discovery), [Schema Validation](/api-shield/management-and-monitoring/#add-endpoints-from-schema-validation), or [manually](/api-shield/management-and-monitoring/#add-endpoints-manually) by method, path, and host. +You can save your endpoints directly from [API Discovery](/api-shield/management-and-monitoring/#add-endpoints-from-api-discovery), [Schema validation](/api-shield/management-and-monitoring/#add-endpoints-from-schema-validation), or [manually](/api-shield/management-and-monitoring/#add-endpoints-manually) by method, path, and host. This will add the specified endpoints to your list of managed endpoints. You can view your list of saved endpoints in the **Endpoint Management** page. @@ -81,7 +81,7 @@ We recommend proceeding with [additional configurations](/api-shield/get-started You can observe Cloudflare suggested rate limits in Endpoint Management for endpoints using session identifiers. Unlike many security tools, these recommended rate limits are per-endpoint and per-session, not site-wide and not based on IP address. When creating a rule, it will be based on only traffic to that specific endpoint from unique visitors during their session. This feature allows you to be very specific and targeted with your rate limit enforcement, both lowering abusive traffic and false positives due to broadly scoped rules. -## Import a learned schema to Schema Validation +## Import a learned schema to Schema validation Cloudflare learns schema parameters via traffic inspection for all endpoints stored in Endpoint Management. You can export OpenAPI schemas in OpenAPI v3.0.0 format by hostname. @@ -103,15 +103,15 @@ You can observe the top sequences in your API traffic that contain endpoints sto [Sequence Mitigation](/api-shield/security/sequence-mitigation/) allows you to enforce request patterns for authenticated clients communicating with your API. Use Sequence Analytics to better understand the request sequences used by your API clients. -You should apply all possible API Shield protections (rate limiting suggestions, Schema Validation, JWT Validation, and mTLS) to API endpoints found in high correlation score sequences that make up the critical request flows in your application. You should also check their specific endpoint order with your development team. +You should apply all possible API Shield protections (rate limiting suggestions, Schema validation, JWT validation, and mTLS) to API endpoints found in high correlation score sequences that make up the critical request flows in your application. You should also check their specific endpoint order with your development team. For more information, refer to [Detecting API abuse automatically using sequence analysis](https://blog.cloudflare.com/api-sequence-analytics) blog post. ## Additional configuration -### Set up JSON Web Tokens (JWT) Validation +### Set up JSON Web Tokens (JWT) validation -Use the Cloudflare API to configure [JSON Web Tokens Validation](/api-shield/security/jwt-validation/), which validates the integrity and validity of JWTs sent by clients to your API or web application. +Use the Cloudflare API to configure [JSON Web Tokens validation](/api-shield/security/jwt-validation/), which validates the integrity and validity of JWTs sent by clients to your API or web application. ### Set up GraphQL Malicious Query Protection diff --git a/src/content/docs/api-shield/index.mdx b/src/content/docs/api-shield/index.mdx index 7e0050930b86325..579d37e4c5667e5 100644 --- a/src/content/docs/api-shield/index.mdx +++ b/src/content/docs/api-shield/index.mdx @@ -40,7 +40,7 @@ A package of features that will do everything for your APIs. Cloudflare API Security products are available to Enterprise customers only, though anyone can set up [Mutual TLS](/api-shield/security/mtls/) with a Cloudflare-managed certificate authority. -The full API Shield security suite is available as an Enterprise-only paid add-on, but all customers can access [Endpoint Management](/api-shield/management-and-monitoring/) and [Schema Validation](/api-shield/security/schema-validation/) functionalities. +The full API Shield security suite is available as an Enterprise-only paid add-on, but all customers can access [Endpoint Management](/api-shield/management-and-monitoring/) and [Schema validation](/api-shield/security/schema-validation/) functionalities. ## Related products diff --git a/src/content/docs/api-shield/management-and-monitoring/developer-portal.mdx b/src/content/docs/api-shield/management-and-monitoring/developer-portal.mdx index b058a258786be39..a8904526ed0dd0d 100644 --- a/src/content/docs/api-shield/management-and-monitoring/developer-portal.mdx +++ b/src/content/docs/api-shield/management-and-monitoring/developer-portal.mdx @@ -22,7 +22,7 @@ Once endpoints are saved If you do not have a schema to upload or to select from a pre-existing schema, export your Endpoint Management schema. For best results, include the learned parameters. - Only API schemas uploaded to Schema Validation 2.0 are available when selecting existing schemas + Only API schemas uploaded to Schema validation 2.0 are available when selecting existing schemas ::: 5. Select **Download project files** to save a local copy of the files that will be uploaded to Cloudflare Pages. Downloading the project files can be helpful if you wish to modify the project in any way and then upload the new version manually to Pages. diff --git a/src/content/docs/api-shield/management-and-monitoring/index.mdx b/src/content/docs/api-shield/management-and-monitoring/index.mdx index f04c7d71b25e78e..d726add9562e4e1 100644 --- a/src/content/docs/api-shield/management-and-monitoring/index.mdx +++ b/src/content/docs/api-shield/management-and-monitoring/index.mdx @@ -29,7 +29,7 @@ When an endpoint is using [Cloudflare Workers](/workers/), the metrics data will 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account and domain. 2. Select **Security** > **API Shield**. -3. Add your endpoints [manually](#add-endpoints-manually), from [Schema Validation](#add-endpoints-from-schema-validation), or from [API Discovery](#add-endpoints-from-api-discovery). +3. Add your endpoints [manually](#add-endpoints-manually), from [Schema validation](#add-endpoints-from-schema-validation), or from [API Discovery](#add-endpoints-from-api-discovery). ## Add endpoints from API Discovery @@ -47,9 +47,9 @@ There are two ways to add API endpoints from Discovery. 2. Select the discovered endpoints you would like to add. 3. Select **Save selected endpoints**. -## Add endpoints from Schema Validation +## Add endpoints from Schema validation -1. Add a schema by [configuring Schema Validation](/api-shield/security/schema-validation/). +1. Add a schema by [configuring Schema validation](/api-shield/security/schema-validation/). 2. On **Review schema endpoints**, save new endpoints to endpoint management by checking the box. 3. Select **Save as draft** or **Save and Deploy**. Endpoints will be saved regardless of whether the Schema is saved as a draft or published. @@ -106,7 +106,7 @@ You can delete endpoints one at a time or in bulk. Cloudflare learns schema parameters via traffic inspection. For all endpoints saved to Endpoint Management, you can export OpenAPI schemas in `v3.0.0` format by hostname. You can also include learned schema parameters. -To protect your API with a learned schema, refer to [Schema Validation](/api-shield/security/schema-validation/#add-validation-by-applying-a-learned-schema-to-an-entire-hostname). +To protect your API with a learned schema, refer to [Schema validation](/api-shield/security/schema-validation/#add-validation-by-applying-a-learned-schema-to-an-entire-hostname). ### Export a schema diff --git a/src/content/docs/api-shield/plans.mdx b/src/content/docs/api-shield/plans.mdx index 3efede5e0bf2e48..997744000fbbbab 100644 --- a/src/content/docs/api-shield/plans.mdx +++ b/src/content/docs/api-shield/plans.mdx @@ -7,11 +7,11 @@ sidebar: --- -Free, Pro, Business, and Enterprise customers without an API Gateway subcription can access [Endpoint Management](/api-shield/management-and-monitoring/) and [Schema Validation](/api-shield/security/schema-validation/), but no other [API Gateway](/api-shield/api-gateway/) features. +Free, Pro, Business, and Enterprise customers without an API Gateway subscription can access [Endpoint Management](/api-shield/management-and-monitoring/) and [Schema validation](/api-shield/security/schema-validation/), but no other [API Gateway](/api-shield/api-gateway/) features. To subscribe to API Gateway, upgrade to an Enterprise plan and contact your account team. -Limits to endpoints apply to Endpoint Management and Schema Validation. Refer to the table below for limits based on your zone plan. +Limits to endpoints apply to Endpoint Management and Schema validation. Refer to the table below for limits based on your zone plan. | Plan type | Saved endpoints | Uploaded schemas | Total uploaded schema size | Rule action | | --- | --- | --- | --- | --- | diff --git a/src/content/docs/api-shield/reference/classic-schema-validation.mdx b/src/content/docs/api-shield/reference/classic-schema-validation.mdx index 1c84f10c98783ba..3c249bb043148f5 100644 --- a/src/content/docs/api-shield/reference/classic-schema-validation.mdx +++ b/src/content/docs/api-shield/reference/classic-schema-validation.mdx @@ -1,56 +1,56 @@ --- -title: Classic Schema Validation (deprecated) +title: Classic Schema validation (deprecated) pcx_content_type: how-to type: overview head: - tag: title - content: Configure Classic Schema Validation (deprecated) + content: Configure Classic Schema validation (deprecated) sidebar: badge: text: Deprecated order: 1 - label: Classic Schema Validation + label: Classic Schema validation --- import { GlossaryTooltip } from "~/components" :::caution[Deprecation notice] -Classic Schema Validation has been deprecated. +Classic Schema validation has been deprecated. -Upload all new schemas to [Schema Validation 2.0](/api-shield/security/schema-validation/). +Upload all new schemas to [Schema validation 2.0](/api-shield/security/schema-validation/). ::: -Use the **API Shield** interface to configure [API Schema Validation](/api-shield/security/schema-validation/), which validates requests according to the API schema you provide. +Use the **API Shield** interface to configure [API Schema validation](/api-shield/security/schema-validation/), which validates requests according to the API schema you provide. -Before you can configure Schema Validation for an API, you must obtain an API Schema file matching our [specifications](/api-shield/security/schema-validation/#specifications). +Before you can configure Schema validation for an API, you must obtain an API Schema file matching our [specifications](/api-shield/security/schema-validation/#specifications). -If you are in the Schema Validation 2.0, you can make changes to your settings but you cannot add any new Classic Schema Validation schemas. +If you are in the Schema validation 2.0, you can make changes to your settings but you cannot add any new Classic Schema validation schemas. :::note This feature is only available for customers on an Enterprise plan. Contact your Cloudflare Customer Success Manager to get access. ::: -## Create an API Shield with Schema Validation +## Create an API Shield with Schema validation -To configure Schema Validation in the Cloudflare dashboard: +To configure Schema validation in the Cloudflare dashboard: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account and domain. 2. Select **Security** > **API Shield**. -3. Go to **Schema Validation** and select **Add schema**. -4. Enter a descriptive name for your policy and optionally edit the expression to trigger Schema Validation. For example, if your API is available at `http://api.example.com/v1`, include a check for the *Hostname* field — equal to `api.example.com` — and a check for the *URI Path* field using a regular expression — matching the regex `^/v1`. +3. Go to **Schema validation** and select **Add schema**. +4. Enter a descriptive name for your policy and optionally edit the expression to trigger Schema validation. For example, if your API is available at `http://api.example.com/v1`, include a check for the *Hostname* field — equal to `api.example.com` — and a check for the *URI Path* field using a regular expression — matching the regex `^/v1`. :::caution[Important] To validate the hostname, you must include the *Hostname* field explicitly in the rule, even if the hostname value is in the schema file. Any hostname value present in the schema file will be ignored. ::: 5. Select **Next**. 6. Upload your schema file. -7. Select **Save** to validate the content of the schema file and deploy the Schema Validation rule. If you get a validation error, ensure that you are using one of the [supported file formats](/api-shield/security/schema-validation/#specifications) and that each endpoint and method pair has a unique operation ID. +7. Select **Save** to validate the content of the schema file and deploy the Schema validation rule. If you get a validation error, ensure that you are using one of the [supported file formats](/api-shield/security/schema-validation/#specifications) and that each endpoint and method pair has a unique operation ID. After deploying your API Shield rule, Cloudflare displays a summary of all API endpoints organized by their protection level and actions that will occur for non-compliant and unprotected requests. -1. In the **Endpoint action** dropdown, select an action for every request that targets a protected endpoint and fails Schema Validation. +1. In the **Endpoint action** dropdown, select an action for every request that targets a protected endpoint and fails Schema validation. 2. In the **Fallthrough action** dropdown, select an action for every request that targets an unprotected endpoint. 3. Optionally, you can save the endpoints to Endpoint Management at the same time the Schema is saved by selecting **Save new endpoints to [endpoint management](/api-shield/management-and-monitoring/)**. Endpoints will be saved regardless of whether the Schema is saved as a draft or published live. 4. Select **Done**. diff --git a/src/content/docs/api-shield/reference/terraform.mdx b/src/content/docs/api-shield/reference/terraform.mdx index 6d923644bf85ea6..87684363f2a51f9 100644 --- a/src/content/docs/api-shield/reference/terraform.mdx +++ b/src/content/docs/api-shield/reference/terraform.mdx @@ -18,11 +18,11 @@ The following resources are available to configure through Terraform: - [`api_shield_operation`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_shield_operation) for configuring endpoints in Endpoint Management. -**Schema Validation 2.0** +**Schema validation 2.0** -- [`api_shield_schema`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_shield_schema) for configuring a schema in [Schema Validation 2.0](/api-shield/security/schema-validation/). -- [`api_shield_schema_validation_settings`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_shield_schema_validation_settings) for configuring zone-level Schema Validation 2.0 settings. -- [`api_shield_operation_schema_validation_settings`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_shield_operation_schema_validation_settings) for configuring operation-level Schema Validation 2.0 settings. +- [`api_shield_schema`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_shield_schema) for configuring a schema in [Schema validation 2.0](/api-shield/security/schema-validation/). +- [`api_shield_schema_validation_settings`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_shield_schema_validation_settings) for configuring zone-level Schema validation 2.0 settings. +- [`api_shield_operation_schema_validation_settings`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_shield_operation_schema_validation_settings) for configuring operation-level Schema validation 2.0 settings. ## Manage API Shield session identifiers @@ -58,14 +58,14 @@ resource "cloudflare_api_shield_operation" "post_image" { } ``` -## Manage Schema Validation 2.0 +## Manage Schema validation 2.0 :::note -It is required to configure Endpoint Management if you want to set up Schema Validation 2.0 using Terraform. +It is required to configure Endpoint Management if you want to set up Schema validation 2.0 using Terraform. ::: -Refer to the example configuration below to manage [Schema Validation 2.0](/api-shield/security/schema-validation/configure/) on your zone. +Refer to the example configuration below to manage [Schema validation 2.0](/api-shield/security/schema-validation/configure/) on your zone. ```tf title="Example configuration" # Schema that should be used for schema validation 2.0 diff --git a/src/content/docs/api-shield/security/index.mdx b/src/content/docs/api-shield/security/index.mdx index 06fe593759d5c0f..2cdfe17258e513b 100644 --- a/src/content/docs/api-shield/security/index.mdx +++ b/src/content/docs/api-shield/security/index.mdx @@ -21,27 +21,27 @@ The following table provides examples of how you might match Cloudflare products | OWASP issue | Example Cloudflare solution | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Broken Object Level Authorization | [Sequence Mitigation], [Schema Validation], [JWT Validation], [Rate Limiting] | -| Broken Authentication | [mTLS](/api-shield/security/mtls/), [JWT Validation], [Exposed Credential Checks](/waf/managed-rules/check-for-exposed-credentials/), [Bot Management](/bots/), [Authentication Posture](/api-shield/security/authentication-posture/) | -| Broken Object Property Level Authorization | [Schema Validation], [JWT Validation] | +| Broken Object Level Authorization | [Sequence Mitigation], [Schema validation], [JWT validation], [Rate Limiting] | +| Broken Authentication | [mTLS](/api-shield/security/mtls/), [JWT validation], [Exposed Credential Checks](/waf/managed-rules/check-for-exposed-credentials/), [Bot Management](/bots/), [Authentication Posture](/api-shield/security/authentication-posture/) | +| Broken Object Property Level Authorization | [Schema validation], [JWT validation] | | Unrestricted Resource Consumption | [Rate Limiting], [Sequence Mitigation], [Bot Management], [GraphQL Query Protection] | -| Broken Function Level Authorization | [Schema Validation], [JWT Validation] | +| Broken Function Level Authorization | [Schema validation], [JWT validation] | | Unrestricted Access to Sensitive Business Flows | [Sequence Mitigation], [Bot Management], [GraphQL Query Protection] | -| Server Side Request Forgery | [Schema Validation], [WAF Managed Rules], [WAF Custom Rules](/waf/custom-rules/) | -| Security Misconfiguration | [Sequence Mitigation], [Schema Validation], [WAF Managed Rules], [GraphQL Query Protection] | +| Server Side Request Forgery | [Schema validation], [WAF managed rules], [WAF custom rules](/waf/custom-rules/) | +| Security Misconfiguration | [Sequence Mitigation], [Schema validation], [WAF managed rules], [GraphQL Query Protection] | | Improper Inventory Management | [Discovery](/api-shield/security/api-discovery/), [Schema Learning](/api-shield/management-and-monitoring/#endpoint-schema-learning) | -| Unsafe Consumption of APIs | [JWT Validation], [WAF Managed Rules] | +| Unsafe Consumption of APIs | [JWT validation], [WAF managed rules] | -[Schema Validation]: /api-shield/security/schema-validation/ +[Schema validation]: /api-shield/security/schema-validation/ [Sequence Mitigation]: /api-shield/security/sequence-mitigation/ -[JWT Validation]: /api-shield/security/jwt-validation/ +[JWT validation]: /api-shield/security/jwt-validation/ [GraphQL Query Protection]: /api-shield/security/graphql-protection/ -[Bot Management]: /bots/ +[Bot management]: /bots/ -[Rate Limiting]: /waf/rate-limiting-rules/ +[Rate limiting]: /waf/rate-limiting-rules/ -[WAF Managed Rules]: /waf/managed-rules/ +[WAF managed rules]: /waf/managed-rules/ diff --git a/src/content/docs/api-shield/security/jwt-validation/configure.mdx b/src/content/docs/api-shield/security/jwt-validation/configure.mdx index b388a63e142da81..32a1f84558aaeb9 100644 --- a/src/content/docs/api-shield/security/jwt-validation/configure.mdx +++ b/src/content/docs/api-shield/security/jwt-validation/configure.mdx @@ -1,29 +1,29 @@ --- -title: Configure JWT Validation +title: Configure JWT validation pcx_content_type: how-to type: overview sidebar: order: 1 head: - tag: title - content: Configure JWT Validation + content: Configure JWT validation --- import { GlossaryTooltip } from "~/components" -Use the Cloudflare API to configure [JWT Validation](/api-shield/security/jwt-validation/), which requires Token Configurations and Token Validation Rules. +Use the Cloudflare API to configure [JWT validation](/api-shield/security/jwt-validation/), which requires token configurations and token validation rules. -## Token Configurations +## Token configurations -A Token Configuration defines a JSON Web Key Set (JWKs), which is used to validate JSON Web Tokens (JWTs) sent by clients and information on where these JWTs are sent in the request. +A token configuration defines a JSON Web Key Set (JWKs), which is used to validate JSON Web Tokens (JWTs) sent by clients and information on where these JWTs are sent in the request. :::note -A zone may have up to four Token Configurations. +A zone may have up to four token configurations. ::: -Token Configurations require the following information: +Token configurations require the following information: |
Field name
| Description | Example | Notes | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | @@ -53,9 +53,9 @@ Cloudflare will remove any fields that are unnecessary from each key and will dr It is highly recommended to validate the output of the API call to check that the resulting keys appear as intended. -## Token Configuration JSON object +## Token configuration JSON object -The example below shows a JSON object with all of the information necessary to create a Token Configuration using the Cloudflare API. If you would like to create JWKs for testing, refer to [mkjwk JSON Web Key Generator](https://mkjwk.org/). +The example below shows a JSON object with all of the information necessary to create a token configuration using the Cloudflare API. If you would like to create JWKs for testing, refer to [mkjwk JSON Web Key Generator](https://mkjwk.org/). ```json title="Example" { @@ -82,9 +82,9 @@ The example below shows a JSON object with all of the information necessary to c } ``` -## Create a Token Configuration using the Cloudflare API +## Create a token configuration using the Cloudflare API -Use cURL or any other API client tool to send the new configuration to Cloudflare’s API to enable JWT Validation. Make sure to replace `{zone_id}` with the relevant zone ID and add your [authentication credentials](/fundamentals/api/get-started/create-token/) header. +Use cURL or any other API client tool to send the new configuration to Cloudflare’s API to enable JWT validation. Make sure to replace `{zone_id}` with the relevant zone ID and add your [authentication credentials](/fundamentals/api/get-started/create-token/) header. ```bash title="Example using cURL" curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/token_validation" \ @@ -113,7 +113,7 @@ curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/token_val }' ``` -The response will be in a Cloudflare `v4` response envelope and the result contains the created configuration. Note the returned ID, as it will be used to reference the Token Configuration when creating Token Validation rules using the API. +The response will be in a Cloudflare `v4` response envelope and the result contains the created configuration. Note the returned ID, as it will be used to reference the token configuration when creating token validation rules using the API. ```json title="Example response" { @@ -147,15 +147,15 @@ The response will be in a Cloudflare `v4` response envelope and the result conta } ``` -## Token Validation Rules +## Token validation rules -Token Validation Rules allow you to enforce a security policy using existing Token Configurations. +Token validation rules allow you to enforce a security policy using existing token configurations. -Token Validation Rules can be configured using the Cloudflare API or [dashboard](/api-shield/security/jwt-validation/#add-a-jwt-validation-rule). +Token validation rules can be configured using the Cloudflare API or [dashboard](/api-shield/security/jwt-validation/#add-a-jwt-validation-rule). |
Field name
| Description | Example | Notes | | ----------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `title` | A human-readable name allowing you to quickly identify it. | JWT Validation on `v1` and `v2.example.com` | Limited to 50 characters. | +| `title` | A human-readable name allowing you to quickly identify it. | JWT validation on `v1` and `v2.example.com` | Limited to 50 characters. | | `description` | A human-readable description that gives more details than `title` and helps to document it. | Log requests without a valid `authorization` header. | Limited to 500 characters. | | `action` | The Firewall Action taken on requests that do not meet `expression`. | `log` | Possible: `log` or `block` | | `enabled` | Enable or disable the rule. | `true` | Possible: `true` or `false` | @@ -166,7 +166,7 @@ Token Validation Rules can be configured using the Cloudflare API or [dashboard] Selectors control the scope of your token validation rule. -If you only need JWT Validation on specific hostnames or subdomains of your apex domain, use the hostname in a selector to include it in the JWT Validation rule. +If you only need JWT validation on specific hostnames or subdomains of your apex domain, use the hostname in a selector to include it in the JWT validation rule. If you need to exclude endpoints from JWT validation that never have valid JWTs used with them (by design), such as a path and method used to establish a valid JWT in the first place, you must use the endpoint’s operation ID to exclude the endpoint in a selector. @@ -181,14 +181,14 @@ A request must also match an operation covered by this rule to trigger an action Refer to [Apply a rule to operations](/api-shield/security/jwt-validation/configure/#apply-a-rule-to-operations) for more information. ::: -A Token Validation rule's expression defines a security policy that a request must meet. +A token validation rule's expression defines a security policy that a request must meet. For example, the expression `is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e")` will trigger if an incoming request does not have at least one valid authentication token. These expressions are similar to [expressions used in Ruleset Engine](/ruleset-engine/rules-language/), with a few key differences: -- The Token Validation rule actions trigger if the expression evaluates `false`, as opposed to Ruleset expressions. -- The Token Validation rules can use dedicated functions that reference Token Configurations. +- The token validation rule actions trigger if the expression evaluates `false`, as opposed to Ruleset expressions. +- The token validation rules can use dedicated functions that reference token configurations. Operators such as `or`, `and`, `eq`, and more are usable in expressions in the same way as in expressions used in Ruleset Engine. @@ -196,8 +196,8 @@ The following functions can be used to interact with JWT Tokens on a request: |
Function
| Description | Notes | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `is_jwt_valid(token_configuration_id String) bool` | `True` if the request has a valid token according to the Token Configuration with the ID `token_configuration_id`. | `token_configuration_id` must be the ID of an existing Token Configuration. This will return `false` if the token is missing from the request. | -| `is_jwt_present(token_configuration_id String) bool` | `True` if the request has a token as configured in the Token Configuration with the ID `token_configuration_id`. | `token_configuration_id` must be the ID of an existing Token Configuration. | +| `is_jwt_valid(token_configuration_id String) bool` | `True` if the request has a valid token according to the token configuration with the ID `token_configuration_id`. | `token_configuration_id` must be the ID of an existing token configuration. This will return `false` if the token is missing from the request. | +| `is_jwt_present(token_configuration_id String) bool` | `True` if the request has a token as configured in the token configuration with the ID `token_configuration_id`. | `token_configuration_id` must be the ID of an existing token configuration. | ### Common use cases @@ -207,13 +207,13 @@ Refer to the following example use cases to understand which security policy to The `is_jwt_present("51231d16-01f1-48e3-93f8-91c99e81288e")` expression will trigger an action if a request is missing a JWT. -It can be combined with a `log` action in the Token Validation rule to log requests that are missing an authentication header. +It can be combined with a `log` action in the token validation rule to log requests that are missing an authentication header. #### Require a valid token The `is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e")` expression will trigger an action if a request does not have a valid JWT. -It can be combined with a `block` action in the Token Validation rule to block requests with no or invalid credentials. +It can be combined with a `block` action in the token validation rule to block requests with no or invalid credentials. #### Require at least one of two possible tokens @@ -227,13 +227,13 @@ The `is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or not is_jwt_valid("5 ## Apply a rule to operations -Only one Token Validation rule can apply to an operation. If an operation is covered by multiple rules, then the rule with highest precedence will take effect. +Only one token validation rule can apply to an operation. If an operation is covered by multiple rules, then the rule with highest precedence will take effect. -You can configure which operations JWT Validation is enforced on using the `selector` field. +You can configure which operations JWT validation is enforced on using the `selector` field. :::note -Selectors will also apply to new operations. New operations that match an existing selector will automatically be covered by that Token Validation rule. +Selectors will also apply to new operations. New operations that match an existing selector will automatically be covered by that token validation rule. ::: For example, the following selector will apply a rule to all operations in `v1.example.com` and `v2.example.com`, except for two operations on these hosts: @@ -379,7 +379,7 @@ The `state` field can be `ignored`, `excluded`, or `included`. Included operatio } ``` -Operations with a `included` state will be covered by the Token Validation Rule. The response also shows the hostnames of included operations in `result.selected_hosts` and shows all hostnames used by all zone operations in `result.available_hosts`. +Operations with a `included` state will be covered by the token validation rule. The response also shows the hostnames of included operations in `result.selected_hosts` and shows all hostnames used by all zone operations in `result.available_hosts`. You can also send an empty object in the request body: @@ -392,11 +392,11 @@ curl --request PUT \ The response will show all zone operations and all possible hosts, which you can use to build your own selector. -## Token Validation Rule JSON object +## Token validation rule JSON object -The example below shows a JSON object with all the necessary information to create a Token Validation Rule using the Cloudflare API. +The example below shows a JSON object with all the necessary information to create a token validation rule using the Cloudflare API. -Replace any Token Configurations IDs and operation IDs with the IDs that exist in your zone. +Replace any token configurations IDs and operation IDs with the IDs that exist in your zone. ```json title="Token Validation Rule JSON example" [ @@ -428,11 +428,11 @@ Replace any Token Configurations IDs and operation IDs with the IDs that exist i ] ``` -## Create a Token Validation Rule using the Cloudflare API +## Create a token Validation rule using the Cloudflare API -Use cURL or any other API client tool to send the new configuration to Cloudflare’s API to enable JWT Validation. Make sure to replace `{zone_id}` with the relevant zone ID and add your [authentication credentials](/fundamentals/api/get-started/create-token/) header. +Use cURL or any other API client tool to send the new configuration to Cloudflare’s API to enable JWT validation. Make sure to replace `{zone_id}` with the relevant zone ID and add your [authentication credentials](/fundamentals/api/get-started/create-token/) header. -Replace any Token Configurations IDs and operation IDs with the IDs that exist in your zone. +Replace any token configurations IDs and operation IDs with the IDs that exist in your zone. A single request can create multiple rules. To do so, pass multiple rule objects in the JSON array of the request body. @@ -511,7 +511,7 @@ The response will be in a Cloudflare `v4` response envelope and the result conta ## Maintenance -### Update Token Configuration +### Update token configuration It is best practice to rotate keys after some time. To support updating the keys, Cloudflare allows up to four keys per configuration. This allows you to add a second, new key to an already existing key. You can start issuing JWTs with the new key only and remove the old key after some time. Additionally, this feature allows the deployment of testing or development keys next to production keys. @@ -554,9 +554,9 @@ curl --request PUT \ Make sure to replace `{zone_id}` with the relevant zone ID and add your [authentication credentials](/fundamentals/api/get-started/create-token/) header. -### Update Token Validation Rules +### Update token validation rules -Token Validation rules can be updated with a `PATCH` request. A single `PATCH` request can update multiple rules. +Token validation rules can be updated with a `PATCH` request. A single `PATCH` request can update multiple rules. A `PATCH` request is specified as a JSON array in the request body. Each item in that array contains updates to a single rule, defined by `id`. @@ -613,9 +613,9 @@ curl --request PATCH \ ]' ``` -## Perform JWT Validation +## Perform JWT validation -Here is an overview of how JWT Validation processes incoming requests: +Here is an overview of how JWT validation processes incoming requests: 1. We extract the JWT in accordance with the configuration from the incoming request. 2. We decode the JWT and look for the JWTs header KID claim. diff --git a/src/content/docs/api-shield/security/jwt-validation/index.mdx b/src/content/docs/api-shield/security/jwt-validation/index.mdx index 9e5bd43805c13f2..fa6d9b128395390 100644 --- a/src/content/docs/api-shield/security/jwt-validation/index.mdx +++ b/src/content/docs/api-shield/security/jwt-validation/index.mdx @@ -1,6 +1,6 @@ --- pcx_content_type: concept -title: JSON Web Tokens Validation +title: JSON Web Tokens validation sidebar: order: 6 @@ -10,15 +10,15 @@ import { GlossaryTooltip } from "~/components" JSON web tokens (JWT) are often used as part of an authentication component on many web applications today. Since JWTs are crucial to identifying users and their access, ensuring the token’s integrity is important. -API Shield’s JWT Validation stops JWT replay attacks and JWT tampering by cryptographically verifying incoming JWTs before they are passed to your API origin. JWT Validation will also stop requests with expired tokens or tokens that are not yet valid. +API Shield’s JWT validation stops JWT replay attacks and JWT tampering by cryptographically verifying incoming JWTs before they are passed to your API origin. JWT validation will also stop requests with expired tokens or tokens that are not yet valid. ## Process -Endpoints must be added to [Endpoint Management](/api-shield/management-and-monitoring/) for JWT Validation to protect them. +Endpoints must be added to [Endpoint Management](/api-shield/management-and-monitoring/) for JWT validation to protect them. -A JWT Validation configuration consists of creating a Token Validation Configuration by adding your JWT signer's public JSON Web Key Set (JWKS) and a JWT Validation Rule by specifying which hostnames and endpoints should be included for validation. +A JWT validation configuration consists of creating a token validation configuration by adding your JWT signer's public JSON Web Key Set (JWKS) and a JWT validation rule by specifying which hostnames and endpoints should be included for validation. -### Add a Token Validation Configuration +### Add a token validation configuration 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account and domain. 2. Go to **Security** > **API Shield** > **Settings**. @@ -31,17 +31,17 @@ Each JWT issuer typically publishes public keys (JWKS) for verification at a kno To automatically keep your JWKS up to date when your identity provider refreshes them, you can use a Worker. Refer to [Configure Workers to automatically update keys](/api-shield/security/jwt-validation/jwt-worker/) to learn more about setting up the Worker. -### Add a JWT Validation Rule +### Add a JWT validation rule 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account and domain. 2. Go to **Security** > **API Shield** > **API Rules**. 3. Add a name for your rule. 4. Select a hostname to protect requests with saved endpoints using the rule. -5. Deselect any endpoints that you want JWT Validation to ignore (for example, an endpoint used to generate a JWT). -6. Select the Token Validation Configuration that corresponds to the incoming requests. +5. Deselect any endpoints that you want JWT validation to ignore (for example, an endpoint used to generate a JWT). +6. Select the token validation configuration that corresponds to the incoming requests. 7. Choose whether to strictly enforce token presence on these endpoints. - - You may not expect 100% of clients to send in JWTs with their requests. If this is the case, choose *Ignore*. JWT Validation will still validate JWTs that are present. + - You may not expect 100% of clients to send in JWTs with their requests. If this is the case, choose *Ignore*. JWT validation will still validate JWTs that are present. - You may otherwise expect all requests to the selected hostname and endpoints to contain JWTs. If this is the case, choose *Mark as non-compliant*. 8. Choose an action to take for non-compliant requests. For example, JWTs that do not pass validation (expired, tampered with, or bad signature tokens) or requests with missing JWTs when *Mark as non-compliant* is selected in the previous step. 9. Select **Save**. @@ -67,11 +67,11 @@ API Shield will verify JSON Web Tokens regardless of whether or not they have th ## Availability -JWT Validation is available for all API Shield customers. Enterprise customers who have not purchased API Shield can preview [API Shield as a non-contract service](https://dash.cloudflare.com/?to=/:account/:zone/security/api-shield) in the Cloudflare dashboard or by contacting your account team. +JWT validation is available for all API Shield customers. Enterprise customers who have not purchased API Shield can preview [API Shield as a non-contract service](https://dash.cloudflare.com/?to=/:account/:zone/security/api-shield) in the Cloudflare dashboard or by contacting your account team. ## Limitations Currently, the following known limitations exist: -1. JWT Validation only operates on JWTs sent in client request headers or cookies. If your clients send in JWTs in a `POST` body, direct that feedback to your account team. -2. JWT Validation only operates for endpoints (host, method, and path) added to Endpoint Management. You can add all of your endpoints to endpoint management through [API Discovery](/api-shield/management-and-monitoring/#add-endpoints-from-api-discovery), [Schema Validation](/api-shield/management-and-monitoring/#add-endpoints-from-schema-validation), [manually via the Cloudflare dashboard](/api-shield/management-and-monitoring/#add-endpoints-manually), or via the [API](/api/resources/api_gateway/subresources/operations/methods/create/). +1. JWT validation only operates on JWTs sent in client request headers or cookies. If your clients send in JWTs in a `POST` body, direct that feedback to your account team. +2. JWT validation only operates for endpoints (host, method, and path) added to Endpoint Management. You can add all of your endpoints to endpoint management through [API Discovery](/api-shield/management-and-monitoring/#add-endpoints-from-api-discovery), [Schema validation](/api-shield/management-and-monitoring/#add-endpoints-from-schema-validation), [manually via the Cloudflare dashboard](/api-shield/management-and-monitoring/#add-endpoints-manually), or via the [API](/api/resources/api_gateway/subresources/operations/methods/create/). diff --git a/src/content/docs/api-shield/security/jwt-validation/jwt-worker.mdx b/src/content/docs/api-shield/security/jwt-validation/jwt-worker.mdx index 75523bc5f55b86f..b75867541650ba3 100644 --- a/src/content/docs/api-shield/security/jwt-validation/jwt-worker.mdx +++ b/src/content/docs/api-shield/security/jwt-validation/jwt-worker.mdx @@ -6,7 +6,7 @@ sidebar: order: 2 head: - tag: title - content: Configure the Worker for JWT Validation + content: Configure the Worker for JWT validation --- Use a Worker to automatically keep your identity provider’s latest public key in the JWT Validation configuration. @@ -15,7 +15,7 @@ Use a Worker to automatically keep your identity provider’s latest public key - Find your zone ID. You can locate this ID in your zone overview in the [Cloudflare dashboard](https://dash.cloudflare.com/). - Find your identity provider’s JSON Web Key Set (JWKs) URL. Identity providers commonly list it in Open Authorization (OAuth) settings. -- Create a [Token Validation Configuration](/api-shield/security/jwt-validation/#add-a-token-validation-configuration). +- Create a [token validation configuration](/api-shield/security/jwt-validation/#add-a-token-validation-configuration). - [Create a new API token](https://dash.cloudflare.com/profile/api-tokens) with the API Gateway `Write` permission. ## Process @@ -64,7 +64,7 @@ curl https://.cloudflareaccess.com/cdn-cgi/access/certs -s | jq 1. [Create a new Worker](/workers/get-started/guide/). 2. Copy and paste the example code below into your new Worker, completely replacing any code that already exists. 3. Replace the current zone ID with your zone ID. -4. Replace the current Token Validation Configuration ID with your Token Validation Configuration. +4. Replace the current token validation configuration ID with your token validation configuration. 5. Replace the current identity provider’s URL with your identity provider’s key URL. :::note diff --git a/src/content/docs/api-shield/security/jwt-validation/transform-rules.mdx b/src/content/docs/api-shield/security/jwt-validation/transform-rules.mdx index e2b705f71acdff8..2aced16c1593205 100644 --- a/src/content/docs/api-shield/security/jwt-validation/transform-rules.mdx +++ b/src/content/docs/api-shield/security/jwt-validation/transform-rules.mdx @@ -13,13 +13,13 @@ You can forward information from a [JSON Web Token (JWT)](/api-shield/security/j Claims are available through the `http.request.jwt.claims` firewall fields. -For example, the following expression will extract the user claim from a token processed by the Token Configuration with `TOKEN_CONFIGURATION_ID`: +For example, the following expression will extract the user claim from a token processed by the token configuration with `TOKEN_CONFIGURATION_ID`: ```txt lookup_json_string(http.request.jwt.claims[""][0], "claim_name") ``` -Refer to [Configure JWT Validation](/api-shield/security/jwt-validation/configure/) for more information about creating a Token Configuration. +Refer to [Configure JWT validation](/api-shield/security/jwt-validation/configure/) for more information about creating a token configuration. ## Create a Transform Rule @@ -31,4 +31,4 @@ As an example, to send the `x-send-jwt-claim-user` request header to the origin, 4. Enter a rule name and a filter expression, if applicable. 5. Choose **Set dynamic**. 6. Set the header name to `x-send-jwt-claim-user`. -7. Set the value to `lookup_json_string(http.request.jwt.claims[""][0], "claim_name")`, where `` is your token configuration ID found in JWT Validation and `claim_name` is the JWT claim you want to add to the header. +7. Set the value to `lookup_json_string(http.request.jwt.claims[""][0], "claim_name")`, where `` is your token configuration ID found in JWT validation and `claim_name` is the JWT claim you want to add to the header. diff --git a/src/content/docs/api-shield/security/schema-validation/configure.mdx b/src/content/docs/api-shield/security/schema-validation/configure.mdx index ad98aab4e63a501..9c8b9ea580cdaeb 100644 --- a/src/content/docs/api-shield/security/schema-validation/configure.mdx +++ b/src/content/docs/api-shield/security/schema-validation/configure.mdx @@ -4,39 +4,39 @@ pcx_content_type: how-to type: overview head: - tag: title - content: Configure Schema Validation + content: Configure Schema validation --- import { GlossaryTooltip } from "~/components" -Schema Validation 2.0 allows all corresponding configuration calls to be made via API. This validation centers more around individual endpoints and lets you set mitigation actions for each endpoint individually. Additionally, you can use Cloudflare-provided learned schemas that we [learn automatically](/api-shield/management-and-monitoring/#endpoint-schema-learning) from your traffic for individual endpoints. +Schema validation 2.0 allows all corresponding configuration calls to be made via API. This validation centers more around individual endpoints and lets you set mitigation actions for each endpoint individually. Additionally, you can use Cloudflare-provided learned schemas that we [learn automatically](/api-shield/management-and-monitoring/#endpoint-schema-learning) from your traffic for individual endpoints. :::note -[Classic Schema Validation documentation](/api-shield/reference/classic-schema-validation/) is available for reference only. +[Classic Schema validation documentation](/api-shield/reference/classic-schema-validation/) is available for reference only. ::: -## Upload schemas via the API to Schema Validation +## Upload schemas via the API to Schema validation 1. Upload a schema. 2. Ensure that your endpoints are added in Endpoint Management. 3. Set the schema to `active` if it is not already done. -4. Set the Schema Validation zone-wide action from `none` to `log`. +4. Set the Schema validation zone-wide action from `none` to `log`. 5. Send test traffic that violates the schema. 6. View test traffic in Security Events by filtering for **Service** > **API Shield - Schema Validation**. 7. Optional: - Set a single endpoint to `block`. - - Set the Schema Validation zone-wide to `block`. + - Set the Schema validation zone-wide to `block`. - Temporarily override all schemas zone-wide to `none`. - Remove the temporary override. -Cloudflare recommends you to rerun test traffic and monitor the HTTP response codes after changing any settings to ensure Schema Validation is operating as expected. +Cloudflare recommends you to rerun test traffic and monitor the HTTP response codes after changing any settings to ensure Schema validation is operating as expected. Settings changes may take a few minutes to implement. :::note -Endpoints must be listed in Endpoint Management for Schema Validation to match requests. +Endpoints must be listed in Endpoint Management for Schema validation to match requests. ::: ## Configuration @@ -72,7 +72,7 @@ curl --request POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_ga } ``` -By default, Schema Validation is disabled for an uploaded schema so that you can inspect it first. You can upload a schema and enable it immediately by setting the form parameter `validation_enabled=true`. +By default, Schema validation is disabled for an uploaded schema so that you can inspect it first. You can upload a schema and enable it immediately by setting the form parameter `validation_enabled=true`. Use a `PATCH` request to activate a schema after inspection. @@ -107,7 +107,7 @@ When a schema is active, it executes the mitigation action specified for each op ### Add new operations to Endpoint Management -Schemas contain a set of servers, paths, and methods, which together define an operation. Schema Validation only acts on the requests to operations which have been added to the API Shield Endpoint Management. If a schema contains operations which have not been added to Endpoint Management, they can be retrieved together with the configuration information about added operations. +Schemas contain a set of servers, paths, and methods, which together define an operation. Schema validation only acts on the requests to operations which have been added to the API Shield Endpoint Management. If a schema contains operations which have not been added to Endpoint Management, they can be retrieved together with the configuration information about added operations. ```bash title="cURL command" curl --request GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas/{schema_id}/operations?feature=schema_info&operation_status=new&page=1&per_page=5000" \ @@ -417,9 +417,9 @@ curl --request PUT "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gat Parameter schemas are updated between every 24 hours up to one week. To ensure that a parameter schema has not been updated during the inspection, Cloudflare recommends that you pass the `last_updated` timestamp of the parameter-schema feature (not the `last_updated` of the whole operation) as an identifier in the timestamp query parameter. ::: -### Disable Schema Validation +### Disable Schema validation -To quickly disable schema validation for a whole zone, use `PATCH`. This operation will override all operation-mitigation actions. +To quickly disable Schema validation for a whole zone, use `PATCH`. This operation will override all operation-mitigation actions. ```bash title="cURL command" curl --request PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/settings/schema_validation" \ diff --git a/src/content/docs/api-shield/security/schema-validation/index.mdx b/src/content/docs/api-shield/security/schema-validation/index.mdx index d78be4be32e15ab..2f4ee5ffcf5a5a6 100644 --- a/src/content/docs/api-shield/security/schema-validation/index.mdx +++ b/src/content/docs/api-shield/security/schema-validation/index.mdx @@ -1,6 +1,6 @@ --- pcx_content_type: concept -title: Schema Validation +title: Schema validation sidebar: order: 8 @@ -12,15 +12,15 @@ import { GlossaryDefinition, GlossaryTooltip, Plan } from "~/components" -Schema Validation allows you to check if incoming traffic complies with a previously supplied API schema. When you provide an API schema or select from a list of learned schema, API Shield creates rules for incoming traffic from the schema definitions. These rules define which traffic is allowed and which traffic gets logged or blocked. +Schema validation allows you to check if incoming traffic complies with a previously supplied API schema. When you provide an API schema or select from a list of learned schema, API Shield creates rules for incoming traffic from the schema definitions. These rules define which traffic is allowed and which traffic gets logged or blocked. -Cloudflare has recently launched Schema Validation 2.0. For help configuring the previous version of Schema Validation for one or more hosts using the dashboard, refer to [Configure Classic Schema Validation](/api-shield/reference/classic-schema-validation/). You can make changes to your Classic Schema Validation settings but you cannot add any new schemas. +Cloudflare has recently launched Schema validation 2.0. For help configuring the previous version of Schema validation for one or more hosts using the dashboard, refer to [Configure Classic Schema validation](/api-shield/reference/classic-schema-validation/). You can make changes to your Classic Schema validation settings but you cannot add any new schemas. -You can migrate to Schema Validation 2.0 manually by uploading your schemas to the new system, or you can wait for a future release where we will add an easy migrate option per-schema. +You can migrate to Schema validation 2.0 manually by uploading your schemas to the new system, or you can wait for a future release where we will add an easy migrate option per-schema. ## Process -Endpoints must be added to [Endpoint Management](/api-shield/management-and-monitoring/) for Schema Validation to protect them. Uploading a schema via the Cloudflare dashboard will automatically add endpoints, or you can manually add them from [API Discovery](/api-shield/security/api-discovery/). +Endpoints must be added to [Endpoint Management](/api-shield/management-and-monitoring/) for Schema validation to protect them. Uploading a schema via the Cloudflare dashboard will automatically add endpoints, or you can manually add them from [API Discovery](/api-shield/security/api-discovery/). If you are uploading a schema via the API or Terraform, you must parse the schema and add your endpoints manually. @@ -35,7 +35,7 @@ To view the contents in your learned schema, refer to [Export a schema](/api-shi 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain. 2. Select **Security** > **API Shield**. -3. Go to **Schema Validation** and select **Add validation**. +3. Go to **Schema validation** and select **Add validation**. 4. Select your schema file for upload. 5. Observe the listed endpoints, their host, method, and path. Any new endpoints will automatically be added to Endpoint Management. 6. Choose an action for the non-compliant requests to your endpoints. @@ -50,7 +50,7 @@ Changes may take a few minutes to process depending on the number of added endpo 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain. 2. Select **Security** > **API Shield**. -3. Go to **Schema Validation** and filter by the learned schema available. +3. Go to **Schema validation** and filter by the learned schema available. 4. Select **Apply learned schema**. 5. Choose an action and select **Apply schema**. @@ -60,7 +60,7 @@ At this time, learned schemas will not overwrite customer-uploaded schemas. If a 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain. 2. Select **Security** > **API Shield**. -3. Go to **Schema Validation** and select **Add Validation**. +3. Go to **Schema validation** and select **Add validation**. 4. Select **Apply learned schema**. 5. Choose a hostname and review the endpoints that will be protected by the learned schema. 6. (Optional) Change the action if a request does not match the schema. @@ -99,16 +99,16 @@ You can use the `cf.api_gateway.fallthrough_triggered` syntax in your own custom 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain. 2. Select **Security** > **API Shield**. -3. Go to **Schema Validation** and select the schema in the Schema list. +3. Go to **Schema validation** and select the schema in the Schema list. 4. Check the multi-select box to select the endpoints shown on the current page. 5. Choose **Select all endpoints**. 6. Select **Change Action**. 7. Choose an action from the dropdown menu. 8. Select **Set action**. -### Change the global default action of Schema Validation +### Change the global default action of Schema validation -Schema Validation’s default action is visible on the main Schema Validation page. This action applies to any endpoint with its action set to `Default`. +Schema validation’s default action is visible on the main Schema validation page. This action applies to any endpoint with its action set to `Default`. - `Log` action: logs events to [Firewall Events](/firewall/). - `Block` action: blocks requests that fail the schema for an endpoint and logs events to [Firewall Events](/firewall/). @@ -118,7 +118,7 @@ To change the default action: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain. 2. Go to **Security** > **API Shield**. -3. Select **Schema Validation**. +3. Select **Schema validation**. 4. Under the default `Log` action, select **Change**. 5. Choose a new action from the dropdown menu. 6. Observe the current action and accept the change by selecting **Change default action** in the popup window. @@ -127,7 +127,7 @@ Alternatively, you can modify the global action via **Security** > **API Shield* ### Change the action of a single endpoint -You can change individual endpoint actions separately from the default action in Schema Validation. +You can change individual endpoint actions separately from the default action in Schema validation. This allows you to be stricter on blocking non-compliant requests on certain endpoints when the default action is `Log`. It can also be used to relax constraints on non-compliant requests on certain endpoints when the default action is set to `Block`. You may want to silence known false positives on an endpoint by setting the action to `None`. @@ -135,18 +135,18 @@ To change the action on an individual endpoint: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain. 2. Go to **Security** > **API Shield**. -3. Select **Schema Validation** and filter the selected endpoint. +3. Select **Schema validation** and filter the selected endpoint. 4. Select the ellipses on the endpoint's row. 5. Select **Change Action**. 6. Choose a new action from the dropdown menu and select **Set action**. -### Disable Schema Validation without changing actions +### Disable Schema validation without changing actions -You can disable Schema Validation entirely for temporary troubleshooting. You can override all actions at once, preventing Schema Validation from taking any action while you complete your troubleshooting. +You can disable Schema validation entirely for temporary troubleshooting. You can override all actions at once, preventing Schema validation from taking any action while you complete your troubleshooting. 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain. 2. Select **Security** > **API Shield**. -3. Go to the **Schema Validation** settings. +3. Go to the **Schema validation** settings. 4. Select **Disable**. Your per-endpoint configurations will be saved when modifying the setting, so that you do not lose your configuration. To re-enable your configurations after troubleshooting, navigate back to the settings and select **Enable**. @@ -157,7 +157,7 @@ To view currently uploaded or learned schemas: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain. 2. Select **Security** > **API Shield**. -3. Go to your **Schema Validation** settings. +3. Go to your **Schema validation** settings. 4. View your schemas under **Uploaded Schemas** and **Learned schemas**. 5. Select **Filter** on the endpoints in either schema. @@ -169,7 +169,7 @@ To delete currently uploaded or learned schemas: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain. 2. Select **Security** > **API Shield**. -3. Go to your **Schema Validation** settings. +3. Go to your **Schema validation** settings. 4. View your schemas under **Uploaded Schemas** and **Learned schemas**. 5. Select the ellipses to access the menu and download or delete the listed schema. @@ -177,11 +177,11 @@ To delete currently uploaded or learned schemas: Cloudflare currently only accepts [OpenAPI v3 schemas](https://spec.openapis.org/oas/v3.0.3.html). The accepted file formats are YAML (`.yml` or `.yaml` file extension) and JSON (`.json` file extension). -OpenAPI schemas generated by different tooling may not be specific enough to import to Schema Validation. We recommend using a third-party tool such as [Swagger Editor](https://swagger.io/tools/swagger-editor/) to ensure that schemas are compliant to the OpenAPI specification. +OpenAPI schemas generated by different tooling may not be specific enough to import to Schema validation. We recommend using a third-party tool such as [Swagger Editor](https://swagger.io/tools/swagger-editor/) to ensure that schemas are compliant to the OpenAPI specification. ## Limitations -Schema Validation supports [OpenAPI Version 3.0.x schemas](https://spec.openapis.org/oas/v3.0.3). OpenAPI 3.1 is not supported yet, and we do not plan to expand support for OpenAPI 2.0. +Schema validation supports [OpenAPI Version 3.0.x schemas](https://spec.openapis.org/oas/v3.0.3). OpenAPI 3.1 is not supported yet, and we do not plan to expand support for OpenAPI 2.0. Currently, API Shield does not support some features of API schemas, including the following: all responses, external references, non-basic path templating, or unique items. @@ -191,26 +191,26 @@ For limits on Free, Pro, Business, or Enterprise customers not subscribed to API ### Required fields -Although not strictly required by the OpenAPI specification, Schema Validation strictly requires these fields. +Although not strictly required by the OpenAPI specification, Schema validation strictly requires these fields. #### `schema` - [`type`](https://spec.openapis.org/oas/v3.0.3#schema-object) - - All schemas require a type to be set. If the specific type is not supported by Schema Validation, it is usually best to simply set the type to `string` instead. + - All schemas require a type to be set. If the specific type is not supported by Schema validation, it is usually best to simply set the type to `string` instead. #### `parameter` - [`schema`](https://spec.openapis.org/oas/v3.0.3#schema-object) - - Schema Validation does not support the content field in parameters. For more details, refer to the [notes on validated and supported fields](#notes-on-validated-and-supported-fields) below. Instead, a schema is strictly required on all parameters objects. + - Schema validation does not support the content field in parameters. For more details, refer to the [notes on validated and supported fields](#notes-on-validated-and-supported-fields) below. Instead, a schema is strictly required on all parameters objects. ### Notes on validated and supported fields -Refer to the information below for more details on Schema Validation's current support for various OpenAPI specification (OAS) objects and fields. +Refer to the information below for more details on Schema validation's current support for various OpenAPI specification (OAS) objects and fields. #### `servers` - [`url`](https://spec.openapis.org/oas/v3.0.3#server-object) - - Schema Validation does not support relative URLs. + - Schema validation does not support relative URLs. - [`variables`](https://spec.openapis.org/oas/v3.0.3#server-variable-object) - Server variables are not validated. @@ -235,7 +235,7 @@ Refer to the information below for more details on Schema Validation's current s - `content` - [Request Body Object](https://spec.openapis.org/oas/v3.0.3#request-body-object) - [Media Type Object](https://spec.openapis.org/oas/v3.0.3#media-type-object) - - Schema Validation is able to validate `application/json` documents. If a given schema allows other content types, Schema Validation will accept those requests without validation. + - Schema validation is able to validate `application/json` documents. If a given schema allows other content types, Schema validation will accept those requests without validation. #### `parameter/schema` @@ -270,13 +270,13 @@ Refer to the information below for more details on Schema Validation's current s - `uint64` - [`uniqueItems`](https://spec.openapis.org/oas/v3.0.3#schema-object) - - This field is currently not validated by Schema Validation. + - This field is currently not validated by Schema validation. ## Body inspection API Shield has the ability to identify body specifications contained in uploaded schemas and validate that the data of incoming API requests adheres to them. -Schema Validation currently supports validating requests with content-type `application/json`. +Schema validation currently supports validating requests with content-type `application/json`. Within the OpenAPI specification, request body schemas are associated to media-ranges (such as `application/*`, `application/xml` or `application/json`). @@ -300,4 +300,4 @@ Media-ranges can also be configured to enforce a `charset` parameter. For this, ## Availability -Schema Validation is available for all customers. Refer to [Plans](/api-shield/plans/) for more information based on your plan type. \ No newline at end of file +Schema validation is available for all customers. Refer to [Plans](/api-shield/plans/) for more information based on your plan type. \ No newline at end of file diff --git a/src/content/docs/api-shield/security/sequence-analytics.mdx b/src/content/docs/api-shield/security/sequence-analytics.mdx index 3c555d9f1dd185d..35a645a2454ae71 100644 --- a/src/content/docs/api-shield/security/sequence-analytics.mdx +++ b/src/content/docs/api-shield/security/sequence-analytics.mdx @@ -40,7 +40,7 @@ To proactively secure your API, you should inspect your highest-scoring sequence Using the above example, if `POST /api/v1/transferFunds` must legitimately always be preceded by `GET /api/v1/users/{user_id}/accounts` and `GET /api/v1/accounts/{account_id}/balance?`, you should create an **Allow** rule in Sequence Mitigation on the final operation of the sequence. -You should also consider applying other API Shield protections to these endpoints ([rate limiting suggestions](/api-shield/security/volumetric-abuse-detection/), [Schema Validation](/api-shield/security/schema-validation/), [JWT Validation](/api-shield/security/jwt-validation/), and [mTLS](/api-shield/security/mtls/)). +You should also consider applying other API Shield protections to these endpoints ([rate limiting suggestions](/api-shield/security/volumetric-abuse-detection/), [Schema validation](/api-shield/security/schema-validation/), [JWT validation](/api-shield/security/jwt-validation/), and [mTLS](/api-shield/security/mtls/)). For more information, refer to our [blog post](https://blog.cloudflare.com/api-sequence-analytics). diff --git a/src/content/docs/api-shield/security/sequence-mitigation/index.mdx b/src/content/docs/api-shield/security/sequence-mitigation/index.mdx index 2138097dfd11abd..031858678e36ddf 100644 --- a/src/content/docs/api-shield/security/sequence-mitigation/index.mdx +++ b/src/content/docs/api-shield/security/sequence-mitigation/index.mdx @@ -78,7 +78,7 @@ You can also explicitly set a priority order by selecting the three dots on your ### Endpoint Management -To track requests to API endpoints, they must be added to [Endpoint Management](/api-shield/management-and-monitoring/). Add your endpoints to endpoint management via [API Discovery](/api-shield/security/api-discovery/), [Schema Validation](/api-shield/security/schema-validation/), or [manually](/api-shield/management-and-monitoring/#add-endpoints-manually) through the Cloudflare dashboard. +To track requests to API endpoints, they must be added to [Endpoint Management](/api-shield/management-and-monitoring/). Add your endpoints to endpoint management via [API Discovery](/api-shield/security/api-discovery/), [Schema validation](/api-shield/security/schema-validation/), or [manually](/api-shield/management-and-monitoring/#add-endpoints-manually) through the Cloudflare dashboard. ### Session Identifiers