Skip to content

Commit 4071b33

Browse files
cloudjumpercatMierengatomek-labuk
authored and
fabianrbz
committed
feat(dev-portal): ACE plugin (#3562)
* Scaffold plugin, add some intro content Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Finish plugin examples Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Add placeholder image, add note about requesting beta access Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Fix examples, add ace png Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Apply suggestions from code review * Apply suggestions from code review Co-authored-by: Mike Swierenga <mike.swierenga@gmail.com> * move up misconfigured routes note, add routes limitation note to if_present Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Mike Swierenga <mike.swierenga@gmail.com> * Fix skip processing example, fix broken link Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: tomek-labuk <tomasz.labuk@konghq.com> * Attempt to fix broken links Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --------- Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> Co-authored-by: Mike Swierenga <mike.swierenga@gmail.com> Co-authored-by: tomek-labuk <tomasz.labuk@konghq.com>
1 parent 218baaa commit 4071b33

File tree

7 files changed

+186
-0
lines changed

7 files changed

+186
-0
lines changed

‎app/_kong_plugins/ace/changelog.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{}

‎app/_kong_plugins/ace/examples/pass-through.yaml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
description: 'The ACE plugin only engages with a request when it matches an operation.'
2+
3+
extended_description: |
4+
The ACE plugin only engages with a request when it matches an operation.
5+
If a request doesn't match, ACE lets the request pass through untouched.
6+
This means that non-matching requests aren't rejected, but ACE also won't perform authentication and authorization on them.
7+
This allows a request to still be processed by other plugins with a [lower priority](/gateway/entities/plugin/#plugin-priority) than ACE.
8+
9+
A limitation of this method is that all traffic outside of APIs linked to an ACE-enabled {{site.base_gateway}} won't be access controlled, this must be configured with a different plugin.
10+
Dev Portal will not be able to protect all operations.
11+
12+
Use cases:
13+
* 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.
14+
* You already have existing traffic and other access controls in place and want to avoid interruption.
15+
16+
title: 'Only engage when a request matches an operation'
17+
18+
weight: 900
19+
20+
requirements:
21+
- "An API or API package in Dev Portal, linked to the control plane that uses the ACE plugin instance"
22+
23+
config:
24+
match_policy: if_present
25+
26+
min_version:
27+
gateway: '3.13'
28+
29+
tools:
30+
- deck
31+
- admin-api
32+
- konnect-api
33+
- kic
34+
- terraform

‎app/_kong_plugins/ace/examples/require-match.yaml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
description: 'Requires every incoming request to match a defined operation from an API or API package in Dev Portal.'
2+
3+
extended_description: |
4+
Requires every incoming request to match a defined operation from an API or API package in Dev Portal.
5+
If a request doesn't match, ACE rejects the request outright with a 404.
6+
All traffic will be rejected except operations or Routes in published APIs linked to an ACE-enabled {{site.base_gateway}}.
7+
8+
{:.danger}
9+
> **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.
10+
11+
title: 'Require all requests to match operation'
12+
13+
weight: 900
14+
15+
requirements:
16+
- "An API or API package in Dev Portal, linked to the control plane that uses the ACE plugin instance"
17+
18+
config:
19+
match_policy: required
20+
21+
min_version:
22+
gateway: '3.13'
23+
24+
tools:
25+
- deck
26+
- admin-api
27+
- konnect-api
28+
- kic
29+
- terraform

‎app/_kong_plugins/ace/examples/skip-processing.yaml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
description: 'Configures the anonymous Consumer to allow anonymous access or multi-authentication.'
2+
extended_description: |
3+
Configure the anonymous Consumer to allow anonymous access or multi-authentication.
4+
5+
When setting the `anonymous` config, there are two outcomes to be aware of:
6+
7+
* Requests that have authenticated with another, higher priority authentication plugin will bypass the ACE plugin, removing the requirement to authenticate as a portal application and be authorized for the given operation.
8+
* Requests that don't authenticate as a Dev Portal application or another authenticated credential will be allowed to pass through the ACE plugin, opening access to all traffic. If this outcome is not desired, a [`request-termination`](/plugins/request-termination/) or similar plugin must be applied to the anonymous consumer, ensuring that unauthenticated access is not allowed.
9+
title: 'Multi-authentication'
10+
11+
weight: 900
12+
13+
requirements:
14+
- "An API or API package in Dev Portal"
15+
- "Another [authentication plugin](/plugins/?category=authentication) configured with `config.anonymous`."
16+
17+
config:
18+
match_policy: if_present
19+
anonymous: anonymous
20+
21+
min_version:
22+
gateway: '3.13'
23+
24+
tools:
25+
- deck
26+
- admin-api
27+
- konnect-api
28+
- kic
29+
- terraform

‎app/_kong_plugins/ace/index.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: 'Access Control Enforcement'
3+
name: 'Access Control Enforcement'
4+
5+
content_type: plugin
6+
7+
publisher: kong-inc
8+
description: 'The ACE plugin manages developer access control to APIs published with Dev Portal.'
9+
10+
products:
11+
- gateway
12+
13+
works_on:
14+
- konnect
15+
16+
min_version:
17+
gateway: '3.13'
18+
19+
topologies:
20+
on_prem:
21+
- hybrid
22+
konnect_deployments:
23+
- hybrid
24+
- cloud-gateways
25+
- serverless
26+
27+
tags:
28+
- traffic-control
29+
30+
icon: ace.png
31+
32+
categories:
33+
- traffic-control
34+
35+
related_resources:
36+
- text: Dev Portal API packaging
37+
url: /dev-portal/api-catalog-and-packaging/
38+
---
39+
40+
{:.warning}
41+
> **Important:** The Access Control Enforcement plugin can only be used with APIs that are linked to a control plane, which is a private beta feature. Contact your account manager for access.
42+
43+
The Access Control Enforcement (ACE) plugin manages developer access control to APIs published with Dev Portal.
44+
45+
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.
46+
47+
The ACE plugin runs *after* all other [authentication plugins](/plugins/?category=authentication) run. For example, if you have [Key Authentication](/plugins/key-auth/) configured and it rejects a request, the ACE plugin *will not* run. To allow for multiple authentication plugins, each must set the [`config.anonymous`](/plugins/ace/reference/#schema--config-anonymous) plugin configuration. Additionally, the choice to allow or reject an `anonymous` result after all authentication plugins have run needs to be controlled as described in [using multiple authentication methods](/gateway/authentication/#using-multiple-authentication-methods).
48+
49+
## Route matching policy
50+
51+
When you configure the ACE plugin, you must set either `required` or `present` for [`config.match_policy`](/plugins/ace/reference/#schema--config-match-policy). This determines how the ACE plugin will behave when a request doesn't match an existing Route.
52+
53+
Keep in mind that misconfigurations can overexpose unintended Routes.
54+
55+
The following table describes what the `match_policy` values do and when to use each:
56+
{% table %}
57+
columns:
58+
- title: Setting
59+
key: setting
60+
- title: Description
61+
key: description
62+
- title: Limitations
63+
key: limitations
64+
- title: Use cases
65+
key: use-case
66+
rows:
67+
- setting: |
68+
`required`
69+
description: |
70+
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}}.
71+
72+
{:.danger}
73+
> **Warning:** Setting the [`match_policy`](/plugins/ace/reference/#schema--config-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.
74+
limitations: |
75+
* Shuts down all traffic outside of ACE-enabled Dev Portal APIs.
76+
* If the plugin is improperly configured, potentially all traffic could be terminated.
77+
use-case: |
78+
* 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.
79+
* You only plan to provide self-service access via your Dev Portal.
80+
- setting: |
81+
`if_present`
82+
description: |
83+
By default, 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.
84+
limitations: |
85+
* 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.
86+
* Since Routes aren't protected by default in this mode, any mistyped or omitted operation in API entities could result in open access.
87+
use-case: |
88+
* 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.
89+
* You already have existing traffic and other access controls in place and want to avoid interruption.
90+
{% endtable %}

‎app/_kong_plugins/ace/reference.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
---
2+
content_type: reference
3+
---

‎app/assets/icons/plugins/ace.png‎

4.65 KB
Loading

0 commit comments

Comments
 (0)