feat(portal): Application <> consumer mapping#5500
Conversation
✅ Deploy Preview for kongdeveloper ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
lena-larionova
force-pushed
the
release/gateway-3.15
branch
from
49d0925 to
b1f5bbd
Compare
|
|
| {% endtable %} | ||
| <!--vale on--> | ||
|
|
||
| When a developer creates an application, {{site.dev_portal}} automatically adds a Kong Identity principal to the application. |
There was a problem hiding this comment.
| When a developer creates an application, {{site.dev_portal}} automatically adds a Kong Identity principal to the application. | |
| Plugins can be applied to an application by linking the application to an existing consumer in API Gateway. This linking is done automatically via Kong Identity principals. When a developer creates an application, {{site.dev_portal}} automatically creates a Kong Identity principal for this application. This principal entity then helps link the application to an existing consumer entity in API Gateway. | |
| Kong Identity does not store any credentials for applications, it is just used for mapping an application to a consumer. |
There was a problem hiding this comment.
This may be way too much internal details for our users. Happy to collaborate to figure out what is the right level of detail that we provide while introducing the role of Kong Identity in this.
There was a problem hiding this comment.
@smritikjaggi Do we want to specify that there are two methods to apply a plugin to an application? So something more like:
"Plugins can be applied to an application by either linking the application to an existing Consumer in Kong Gateway or applying the plugin directly to the associated principal."
There was a problem hiding this comment.
With the wording for applying plugins to principals, there is not a mechanism to apply a plugin "directly" to a principal (i.e., through a direct principal to plugin relationship) in the same way that plugins can be applied to entities like consumers, routes, and services. Conditional execution logic can be used to target the specific principal, but this is an indirect and loosely coupled way of associating plugins with principals.
| {% endtable %} | ||
| <!--vale on--> | ||
|
|
||
| When a developer creates an application, {{site.dev_portal}} automatically adds a Kong Identity principal to the application. |
There was a problem hiding this comment.
This may be way too much internal details for our users. Happy to collaborate to figure out what is the right level of detail that we provide while introducing the role of Kong Identity in this.
| When a developer creates an application, {{site.dev_portal}} automatically adds a Kong Identity principal to the application. | ||
|
|
||
| You can apply plugins to an application in two different ways: | ||
| * **Conditional plugin execution (recommended):** Use [conditional plugin execution](/gateway/configure-conditional-plugin-execution/) with an expression that references the application's `principal.id`. This applies the plugin based on the application's principal, without mapping the application to a Consumer. |
There was a problem hiding this comment.
| * **Conditional plugin execution (recommended):** Use [conditional plugin execution](/gateway/configure-conditional-plugin-execution/) with an expression that references the application's `principal.id`. This applies the plugin based on the application's principal, without mapping the application to a Consumer. | |
| * **Conditional plugin execution (recommended):** Use [conditional plugin execution](/gateway/configure-conditional-plugin-execution/) with an expression that references the application's `principal.id`. This applies the plugin based on the application's principal, without mapping the application to a Consumer. This configuration can be managed within Kong Identity and API Gateway |
There was a problem hiding this comment.
I am hesitant to call this approach recommended as it is valuable for only net new customers. Our existing customers all fall in the second bucket for consumer scoped plugins because they started their journey in API Gateway and then adopted Dev Portal.
It is also likely that net new customers also start their journey in API Gateway and adopt Dev Portal after, making them fall in the second bucket of consumer scoped plugin. Gateway forms our entry point overall in Konnect.
There was a problem hiding this comment.
After discussing with Mike, another way to write this is - "if you are starting net new and have not created consumers, you can directly apply plugins to the principal".
There was a problem hiding this comment.
I'll turn this into a table so it's easier to convey this info
| Keep the following in mind when you map applications to Consumers: | ||
| * Both the [KAA and ACE plugins](/catalog/apis/#allow-developers-to-consume-your-api) look up principals to resolve the Consumer mapped to an application. | ||
| * An application maps to a single Consumer (a 1:1 mapping through one principal). | ||
| * The mapping is a loose, string-based mapping. The {{site.dev_portal}} does not validate that the Consumer exists on the Gateway. |
There was a problem hiding this comment.
This is incorrect. Mapping is done via consumer ID, so the consumer must exist before mapping can be done successfully. We should confirm if the API will give a 404 or bad request for an incorrect consumer ID. I know that the UI does not allow to map to a consumer that does not exist.
There was a problem hiding this comment.
The response for an incorrect consumer ID will be a 404
| * The mapping is a loose, string-based mapping. The {{site.dev_portal}} does not validate that the Consumer exists on the Gateway. | ||
| * Application registrations for APIs that are linked to the same Gateway Service will share the same effective Consumer mapping. | ||
| Updating the mapping for one registration updates it for all registrations that resolve to the same Gateway context. | ||
| * Applying plugins to applications is only available on v3 {{site.dev_portal}}s. |
There was a problem hiding this comment.
This is true for the conditional execution approach also, lets add it in that section too.
There was a problem hiding this comment.
I'll break this section into it's own h3 so it will apply to both.
| * **Conditional plugin execution (recommended):** Use [conditional plugin execution](/gateway/configure-conditional-plugin-execution/) with an expression that references the application's `principal.id`. This applies the plugin based on the application's principal, without mapping the application to a Consumer. | ||
| * **Consumer-scoped plugins:** [Map the application to an existing Gateway Consumer](#map-an-application-to-a-consumer), then configure Consumer-scoped plugins on that Consumer. This is a common starting point if you already have Consumers configured. | ||
|
|
||
| ### Apply a plugin to an application using a principal |
There was a problem hiding this comment.
| ### Apply a plugin to an application using a principal | |
| ### Apply a plugin to an application using a Kong Identity Principal |
| These plugins are responsible for applying authentication and authorization on the Gateway Service or control plane. | ||
| The [authentication strategy](/dev-portal/auth-strategies/) that you select for the API defines how clients authenticate. | ||
|
|
||
| Both plugins also look up principals to resolve any [plugins applied to a {{site.dev_portal}} application](/dev-portal/self-service/#map-an-application-to-a-consumer), so that Consumer or principal-scoped plugins apply to the application's traffic. |
There was a problem hiding this comment.
| Both plugins also look up principals to resolve any [plugins applied to a {{site.dev_portal}} application](/dev-portal/self-service/#map-an-application-to-a-consumer), so that Consumer or principal-scoped plugins apply to the application's traffic. | |
| For Gateway v3.15+, both plugins also look up Kong Identity principals to resolve any [plugins applied to a {{site.dev_portal}} application](/dev-portal/self-service/#map-an-application-to-a-consumer), so that Consumer or principal-scoped plugins apply to the application's traffic. |
There was a problem hiding this comment.
Pull request overview
Adds a new Dev Portal self-service reference page (replacing the prior landing-page YAML) and introduces guidance for mapping Dev Portal Applications to Gateway Consumers / principals so plugin policies can be applied at the application level.
Changes:
- Replaces the
/dev-portal/self-service/landing page YAML with a full reference doc atapp/dev-portal/self-service.md. - Documents two approaches for applying plugins to Dev Portal applications (principal-based conditional execution and Consumer-scoped plugins via mapping).
- Updates ACE / KAA-vs-ACE includes to mention principal lookups and link into the new self-service content.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| app/dev-portal/self-service.md | New reference page covering developer self-service plus new “apply plugins to applications” and app↔Consumer mapping content. |
| app/_landing_pages/dev-portal/self-service.yaml | Removes the old landing-page implementation for self-service. |
| app/_includes/plugins/ace/ace-overview.md | Updates ACE overview wording and adds a cross-link to the new application/plugin mapping guidance. |
| app/_includes/dev-portal/kaa-vs-ace.md | Adds a note about principal lookups and links into the self-service mapping/plugin guidance. |
|
|
||
| ### Map an application to a Consumer | ||
|
|
||
| Mapping an application to a Consumer requires the [Consumer Viewer](/konnect-platform/teams-and-roles/#control-planes) role, granted for each API instance registered by the application. |
| Plugins can be applied to an application by either linking the application to an existing Consumer in {{site.base_gateway}} or applying the plugin via conditional execution logic to the associated principal. | ||
| When a developer creates an application, {{site.dev_portal}} automatically creates a {{site.identity}} principal for this application. | ||
| This principal entity then helps link the application to an existing Consumer entity in {{site.base_gateway}}. | ||
| {{site.identity}} doesn't store any credentials for applications, it is just used for mapping an application to a consumer. |
| Unlike the KAA plugin, the ACE plugin can link to control planes to configure access control and create API package operations for Gateway Services. | ||
| API packages use the ACE plugin to manage developer access control to APIs. | ||
|
|
||
| If you [apply a plugin to a {{site.dev_portal}} application](/dev-portal/self-service/#map-an-application-to-a-consumer), the ACE plugin looks up the application's principal to resolve the mapped Consumer at runtime, so any Consumer or principal-scoped plugins apply to the application's traffic. |
| These plugins are responsible for applying authentication and authorization on the Gateway Service or control plane. | ||
| The [authentication strategy](/dev-portal/auth-strategies/) that you select for the API defines how clients authenticate. | ||
|
|
||
| Both plugins also look up principals to resolve any [plugins applied to a {{site.dev_portal}} application](/dev-portal/self-service/#map-an-application-to-a-consumer), so that Consumer or principal-scoped plugins apply to the application's traffic. |
| ## Apply plugins to applications {% new_in 3.15 %} | ||
|
|
||
| You can apply {{site.base_gateway}} plugins to your {{site.dev_portal}} applications. | ||
| This lets you enforce business logic, such as rate limiting or IP restriction, on the credentials that an application uses to access your APIs. | ||
|
|
|
Per https://kongstrong.slack.com/archives/C0AP3D8LJC8/p1781113523237129?thread_ts=1781111919.183199&cid=C0AP3D8LJC8, I will be rebasing this and pointing it to the Kong Identity release branch instead. |
Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
…rt yaml to md Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
cloudjumpercat
force-pushed
the
feat/application-consumer-mapping
branch
from
dc696c7 to
f1cf8cc
Compare
cloudjumpercat
changed the base branch from
release/gateway-3.15
to
release/kong-identity-m0
Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
Description
Fixes #5317
Preview Links
Note for reviewers:
Checklist
descriptionentry in frontmatter.