From 6e2109706b454268bdcc2d4f6d0b48234470d881 Mon Sep 17 00:00:00 2001 From: Patricia Loraine Santa Ana Date: Fri, 17 Jan 2025 10:54:44 -0800 Subject: [PATCH 1/5] authentication posture --- .../endpoint-labels.mdx | 7 ++- .../security/authentication-posture.mdx | 46 +++++++++++++++++++ .../partials/api-shield/label-methodology.mdx | 9 ++++ 3 files changed, 58 insertions(+), 4 deletions(-) create mode 100644 src/content/docs/api-shield/security/authentication-posture.mdx create mode 100644 src/content/partials/api-shield/label-methodology.mdx diff --git a/src/content/docs/api-shield/management-and-monitoring/endpoint-labels.mdx b/src/content/docs/api-shield/management-and-monitoring/endpoint-labels.mdx index 0328e68cfc79adc..ae6c75e9315adb8 100644 --- a/src/content/docs/api-shield/management-and-monitoring/endpoint-labels.mdx +++ b/src/content/docs/api-shield/management-and-monitoring/endpoint-labels.mdx @@ -8,6 +8,8 @@ sidebar: --- +import { Render } from "~/components" + API Shield's labeling service will help you organize your endpoints and address vulnerabilities in your API. The labeling service comes with managed and user-defined labels. Today, managed labels are useful for organizing endpoints by use case. In a future release, managed labels will automatically label endpoints by use case and those with informative or security risks, alerting you on endpoints that need attention. @@ -50,10 +52,7 @@ You can filter your endpoints based on the labels. Cloudflare will only add authentication labels to endpoints with successful response codes. Refer to the below table for more details. ::: -| Description | 2xx response codes | 4xx, 5xx response codes | -| --- | --- | --- | -| If all requests are missing authentication, Cloudflare will apply the label: | `cf-missing-auth` | Without successful responses, no label will be added. | -| If only some requests are missing authentication, Cloudflare will apply the label: | `cf-mixed-auth` | Without successful responses, no label will be added. | + ## Create a label diff --git a/src/content/docs/api-shield/security/authentication-posture.mdx b/src/content/docs/api-shield/security/authentication-posture.mdx new file mode 100644 index 000000000000000..4f42dd175e32f89 --- /dev/null +++ b/src/content/docs/api-shield/security/authentication-posture.mdx @@ -0,0 +1,46 @@ +--- +pcx_content_type: concept +type: overview +title: Authentication Posture +sidebar: + order: 9 + +--- + +import { GlossaryTooltip, Render } from "~/components" + +Authentication Posture helps users identify authentication misconfigurations for APIs and alerts of their presence. + +For example, a security team member may believe that their API hosted at `/api/v1/users` and `/api/v1/orders` are guarded by the fact that only authenticated users can interact with the endpoints. However, bugs in origin API authentication policies may lead to broken authentication vulnerabilities. Authentication Posture with API Shield details the authentication status of successful requests to your API endpoints, alerting to potential misconfigurations. + +Consider a typical e-commerce application. Users can browse items and prices without being logged in. However, to retrieve order details with the `GET /api/v1/orders/{order_id}` endpoint, this example application requires users to log in to their account and pass the subsequent Authorization HTTP header in all requests. Cloudflare will alert via [Security Center Insights](/security-center/security-insights/) and [Endpoint Management labels](/api-shield/management-and-monitoring/endpoint-labels/) if successful requests are sent to the `GET /api/v1/orders/{order_id}` endpoint or any other endpoint without authentication when session identifiers are configured. + +## Process + +After configuring [session identifiers](/api-shield/get-started/#session-identifiers), API Shield continuously scans your traffic for successful requests without authentication and labels your endpoints on a daily basis. Refer to the table below for our labeling methodology: + + + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain. +2. Go to **Security** > **API Shield** > **Endpoint Management**. +3. Filter Endpoint Management by the `cf-risk-missing-auth` or `cf-risk-mixed-auth` labels. +4. Select an endpoint to see its authentication posture details on the endpoint details page. +5. Choose between the 24-hour and 7-day view options, and note any authentication changes over time. + +The main authentication widget displays how many successful requests over the last seven days had session identifiers included with them, and which identifiers were included with the traffic. + +The authentication-over-time chart shows a detailed breakdown over time of how clients successfully interacted with your API and which identifiers were used. A large increase in unauthenticated traffic may signal a security incident. Similarly, any successful unauthenticated traffic on an endpoint that is expected to be 100% authenticated can be a cause for concern. + +Work with your development team to understand which authentication policies may need to be corrected on your API to stop unauthenticated traffic. + +## Stop unauthenticated traffic with Cloudflare + +You can use the `cf.api_gateway.auth_id_present` field in [custom rules](/waf/custom-rules/) to trigger when the API Shield configured session identifiers are present or absent on a request. Since this rule would cover your entire zone, Cloudflare recommends adding a host and path match in the rule to pinpoint the protection to exactly what is needed. + +## Limitations + +Authentication Posture can only apply when customers accurately set up session identifiers in API Shield. As a reminder, session identifiers are meant to uniquely identify authenticated users of your API. If you are unsure of your API’s session identifier, consult with your development team. + +## Availability + +Authentication Posture is available for all Enterprise subscriptions with API Shield. \ No newline at end of file diff --git a/src/content/partials/api-shield/label-methodology.mdx b/src/content/partials/api-shield/label-methodology.mdx new file mode 100644 index 000000000000000..d4fca4a2f537769 --- /dev/null +++ b/src/content/partials/api-shield/label-methodology.mdx @@ -0,0 +1,9 @@ +--- +{} + +--- + +| Description | 2xx response codes | 4xx, 5xx response codes | +| --- | --- | --- | +| If all requests are missing authentication, Cloudflare will apply the label: | `cf-missing-auth` | Without successful responses, no label will be added. | +| If only some requests are missing authentication, Cloudflare will apply the label: | `cf-mixed-auth` | Without successful responses, no label will be added. | From b83fb27cbe5410ba671bcc5ca94b10f9f451af18 Mon Sep 17 00:00:00 2001 From: Patricia Loraine Santa Ana Date: Fri, 17 Jan 2025 11:29:04 -0800 Subject: [PATCH 2/5] typo --- src/content/docs/api-shield/security/authentication-posture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/api-shield/security/authentication-posture.mdx b/src/content/docs/api-shield/security/authentication-posture.mdx index 4f42dd175e32f89..4da7fc478d5fef4 100644 --- a/src/content/docs/api-shield/security/authentication-posture.mdx +++ b/src/content/docs/api-shield/security/authentication-posture.mdx @@ -39,7 +39,7 @@ You can use the `cf.api_gateway.auth_id_present` field in [custom rules](/waf/cu ## Limitations -Authentication Posture can only apply when customers accurately set up session identifiers in API Shield. As a reminder, session identifiers are meant to uniquely identify authenticated users of your API. If you are unsure of your API’s session identifier, consult with your development team. +Authentication Posture can only apply when customers accurately set up session identifiers in API Shield. As a reminder, session identifiers are meant to uniquely identify authenticated users of your API. If you are unsure of your API's session identifier, consult with your development team. ## Availability From e2cc91841283736070ddc580a48a5167078d67b1 Mon Sep 17 00:00:00 2001 From: Patricia Loraine Santa Ana Date: Fri, 17 Jan 2025 11:56:00 -0800 Subject: [PATCH 3/5] transition --- .../docs/api-shield/security/authentication-posture.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/docs/api-shield/security/authentication-posture.mdx b/src/content/docs/api-shield/security/authentication-posture.mdx index 4da7fc478d5fef4..5550e4b5bb03934 100644 --- a/src/content/docs/api-shield/security/authentication-posture.mdx +++ b/src/content/docs/api-shield/security/authentication-posture.mdx @@ -17,10 +17,12 @@ Consider a typical e-commerce application. Users can browse items and prices wit ## Process -After configuring [session identifiers](/api-shield/get-started/#session-identifiers), API Shield continuously scans your traffic for successful requests without authentication and labels your endpoints on a daily basis. Refer to the table below for our labeling methodology: +After configuring [session identifiers](/api-shield/get-started/#session-identifiers), API Shield continuously scans your traffic for successful requests without authentication and labels your endpoints on a daily basis. Refer to the table below for our labeling methodology. +To examine an endpoint’s authentication details in the Cloudflare dashboard: + 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain. 2. Go to **Security** > **API Shield** > **Endpoint Management**. 3. Filter Endpoint Management by the `cf-risk-missing-auth` or `cf-risk-mixed-auth` labels. From dee9c944e9eddb6ba6c4179c84ca3508f2efb2b5 Mon Sep 17 00:00:00 2001 From: Patricia Loraine Santa Ana Date: Fri, 17 Jan 2025 11:56:55 -0800 Subject: [PATCH 4/5] typo again --- src/content/docs/api-shield/security/authentication-posture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/api-shield/security/authentication-posture.mdx b/src/content/docs/api-shield/security/authentication-posture.mdx index 5550e4b5bb03934..38e04a440da3e97 100644 --- a/src/content/docs/api-shield/security/authentication-posture.mdx +++ b/src/content/docs/api-shield/security/authentication-posture.mdx @@ -21,7 +21,7 @@ After configuring [session identifiers](/api-shield/get-started/#session-identif -To examine an endpoint’s authentication details in the Cloudflare dashboard: +To examine an endpoint's authentication details in the Cloudflare dashboard: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain. 2. Go to **Security** > **API Shield** > **Endpoint Management**. From cff905ce86bef35026d02e46ea53017c2b815169 Mon Sep 17 00:00:00 2001 From: Patricia Loraine Santa Ana Date: Fri, 17 Jan 2025 12:55:24 -0800 Subject: [PATCH 5/5] changelog entry --- src/content/changelogs/api-shield.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/content/changelogs/api-shield.yaml b/src/content/changelogs/api-shield.yaml index 087ed00e67fde43..21f1eec104422dc 100644 --- a/src/content/changelogs/api-shield.yaml +++ b/src/content/changelogs/api-shield.yaml @@ -5,6 +5,11 @@ productLink: "/api-shield/" productArea: Application security productAreaLink: /fundamentals/reference/changelog/security/ entries: + - publish_date: "2025-01-16" + title: API Authentication Posture + description: |- + Customers will see per-endpoint authentication details inside API Shield's [Endpoint Management](/api-shield/management-and-monitoring/) for zones with configured session identifiers. + - publish_date: "2024-12-19" title: Automatically applied endpoint risk labels description: |-