diff --git a/app/_kong_plugins/ace/changelog.json b/app/_kong_plugins/ace/changelog.json new file mode 100644 index 0000000000..9e26dfeeb6 --- /dev/null +++ b/app/_kong_plugins/ace/changelog.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/app/_kong_plugins/ace/examples/pass-through.yaml b/app/_kong_plugins/ace/examples/pass-through.yaml new file mode 100644 index 0000000000..39a320fd3b --- /dev/null +++ b/app/_kong_plugins/ace/examples/pass-through.yaml @@ -0,0 +1,39 @@ +description: 'The ACE plugin only engages with a request when it matches an operation.' + +extended_description: | + The ACE plugin only engages with a request when it matches an operation. + If a request doesn't match, ACE lets the request pass through untouched. + This means that non-matching requests aren't rejected, but ACE also won't perform authentication and authorization on them. + This allows a request to still be processed by other plugins with a [lower priority](/gateway/entities/plugin/#plugin-priority) than ACE. + + A limitation of this method is that all traffic outside of published APIs linked to an ACE-enabled {{site.base_gateway}} won't be access controlled, this must be configured with a different plugin. + Dev Portal will not be able to protect all operations. + + Use cases: + * You have an environment where some Gateway Services or Routes are governed by Dev Portal–exposed APIs (with ACE), while others are regular Routes that should be left alone. + * You already have existing traffic and other access controls in place and want to avoid interruption. + +title: 'Only engage when a request matches an operation' + +weight: 900 + +requirements: +- "An API or API package in Dev Portal" + +config: + match_policy: required + redis: + host: localhost + port: 6379 + sync_rate: 1 + anonymous: anonymous + +min_version: + gateway: '3.13' + +tools: + - deck + - admin-api + - konnect-api + - kic + - terraform \ No newline at end of file diff --git a/app/_kong_plugins/ace/examples/require-match.yaml b/app/_kong_plugins/ace/examples/require-match.yaml new file mode 100644 index 0000000000..eeb72c16ef --- /dev/null +++ b/app/_kong_plugins/ace/examples/require-match.yaml @@ -0,0 +1,34 @@ +description: 'Requires every incoming request to match a defined operation from an API or API package in Dev Portal.' + +extended_description: | + Requires every incoming request to match a defined operation from an API or API package in Dev Portal. + If a request doesn't match, ACE rejects the request outright with a 404. + All traffic will be rejected except operations or Routes in published APIs linked to an ACE-enabled {{site.base_gateway}}. + + {:.danger} + > **Warning:** Setting the `match_policy` to `required` can **block all traffic with a 404**. Any undefined endpoints will be blocked. If you accidentally enable this in your control planes, this could cause a potential outage in production. + +title: 'Require all requests to match operation' + +weight: 900 + +requirements: +- "An API or API package in Dev Portal" + +config: + match_policy: required + redis: + host: localhost + port: 6379 + sync_rate: 1 + anonymous: anonymous + +min_version: + gateway: '3.13' + +tools: + - deck + - admin-api + - konnect-api + - kic + - terraform \ No newline at end of file diff --git a/app/_kong_plugins/ace/examples/skip-processing.yaml b/app/_kong_plugins/ace/examples/skip-processing.yaml new file mode 100644 index 0000000000..33c9a8320e --- /dev/null +++ b/app/_kong_plugins/ace/examples/skip-processing.yaml @@ -0,0 +1,26 @@ +description: 'The ACE plugin skips processing entirely.' + +title: 'Skip processing' + +weight: 900 + +requirements: +- "An API or API package in Dev Portal" + +config: + match_policy: ignored + redis: + host: localhost + port: 6379 + sync_rate: 1 + anonymous: anonymous + +min_version: + gateway: '3.13' + +tools: + - deck + - admin-api + - konnect-api + - kic + - terraform \ No newline at end of file diff --git a/app/_kong_plugins/ace/index.md b/app/_kong_plugins/ace/index.md new file mode 100644 index 0000000000..b4c85e640f --- /dev/null +++ b/app/_kong_plugins/ace/index.md @@ -0,0 +1,85 @@ +--- +title: 'ACE' +name: 'ACE' + +content_type: plugin + +publisher: kong-inc +description: 'The ACE plugin manages developer access control to APIs published with Dev Portal.' + +products: + - gateway + +works_on: + - konnect + +min_version: + gateway: '3.13' + +topologies: + on_prem: + - hybrid + konnect_deployments: + - hybrid + - cloud-gateways + - serverless + +tags: + - traffic-control + +icon: ace.png + +categories: + - traffic-control + +related_resources: + - text: Dev Portal API packaging + url: /dev-portal/api-catalog-and-packaging/ +--- + +The ACE plugin manages developer access control to APIs published with Dev Portal. + +Previously, when you created an API catalog in Dev Portal and linked the APIs to a Gateway Service, {{site.konnect_short_name}} would automatically apply the {{site.konnect_short_name}} application auth (KAA) plugin automatically. API packages uses the ACE plugin instead to manage developer access control to APIs. Unlike the KAA plugin, the ACE plugin can link to control planes to configure access control and create operations for Gateway Services in those control planes. + +The ACE plugin runs *after* all other [authentication plugins](/plugins/?category=authentication) run. For example, if you have Key Authentication configured and it rejects a request, the ACE plugin *will not* run. If you're using the `config.anonymous` ACE plugin configuration, the [plugin priority](/gateway/entities/plugin/#plugin-priority) needs to be set in such a way that it executes after all other authentication plugins. For example, you can set a provisional priority of 949 so the plugin runs after KAA (which has a priority of 950). + +## Route matching policy + +When you configure the ACE plugin, you must set either `required` or `present` for `config.match_policy`. This determines how the ACE plugin will behave when a request doesn't match an existing Route. + +The following table describes what the `match_policy` values do and when to use each: +{% table %} +columns: + - title: Setting + key: setting + - title: Description + key: description + - title: Limitations + key: limitations + - title: Use cases + key: use-case +rows: + - setting: | + `required` + description: | + Requires every incoming request to match a defined operation from an API or API package in Dev Portal. If a request doesn't match, ACE rejects the request outright with a 404. All traffic will be rejected except operations or Routes in published APIs linked to an ACE-enabled {{site.base_gateway}}. + + {:.danger} + > **Warning:** Setting the `match_policy` to `required` can **block all traffic with a 404**. Any undefined endpoints will be blocked. If you accidentally enable this in your control planes, this could cause a potential outage in production. + limitations: | + * Misconfigurations can overexpose unintended Routes. + * Shuts down all traffic outside of published Dev Portal APIs. + * If the plugin is improperly configured, potentially all traffic could be terminated. + use-case: | + * You want to lock down {{site.konnect_short_name}} so that only traffic that is part of an explicitly defined API operation is allowed through. + * You only plan to provide self-service access via your Dev Portal. + - setting: | + `if_present` + description: | + The ACE plugin only engages with a request when it matches an operation. If a request doesn't match, ACE lets the request pass through untouched. This means that non-matching requests aren't rejected, but ACE also won't perform authentication and authorization on them. This allows a request to still be processed by other plugins with a [lower priority](/gateway/entities/plugin/#plugin-priority) than ACE. + limitations: | + All traffic outside of published APIs linked to an ACE-enabled {{site.base_gateway}} won't be access controlled, this must be configured with a different plugin. Dev Portal will not be able to protect all operations. + use-case: | + * You have an environment where some Gateway Services or Routes are governed by Dev Portal–exposed APIs (with ACE), while others are regular Routes that should be left alone. + * You already have existing traffic and other access controls in place and want to avoid interruption. +{% endtable %} \ No newline at end of file diff --git a/app/_kong_plugins/ace/reference.md b/app/_kong_plugins/ace/reference.md new file mode 100644 index 0000000000..a00b1c79b1 --- /dev/null +++ b/app/_kong_plugins/ace/reference.md @@ -0,0 +1,3 @@ +--- +content_type: reference +--- \ No newline at end of file