From 183a0281b8f9ce652e88015a163706cf098d3dbf Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Mon, 8 Jun 2026 15:47:05 -0500 Subject: [PATCH 1/7] Update reference content Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_includes/dev-portal/kaa-vs-ace.md | 2 + app/_includes/plugins/ace/ace-overview.md | 2 + .../dev-portal/self-service.yaml | 68 +++++++++++++++++++ 3 files changed, 72 insertions(+) diff --git a/app/_includes/dev-portal/kaa-vs-ace.md b/app/_includes/dev-portal/kaa-vs-ace.md index 4a40857ff0..fe1668bf3f 100644 --- a/app/_includes/dev-portal/kaa-vs-ace.md +++ b/app/_includes/dev-portal/kaa-vs-ace.md @@ -5,6 +5,8 @@ When you link an API to a Gateway, you have two options: 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 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. + The following table can help you decide which option to pick: {% table %} diff --git a/app/_includes/plugins/ace/ace-overview.md b/app/_includes/plugins/ace/ace-overview.md index 86dc40d945..cc991e35c2 100644 --- a/app/_includes/plugins/ace/ace-overview.md +++ b/app/_includes/plugins/ace/ace-overview.md @@ -4,6 +4,8 @@ You can use the ACE plugin as an alternative to the {{site.konnect_short_name}} 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 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. + 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. diff --git a/app/_landing_pages/dev-portal/self-service.yaml b/app/_landing_pages/dev-portal/self-service.yaml index 84cf98a90e..3379fbfe05 100644 --- a/app/_landing_pages/dev-portal/self-service.yaml +++ b/app/_landing_pages/dev-portal/self-service.yaml @@ -235,7 +235,75 @@ rows: * Each application can have a maximum of 20 API keys. * Each API that uses the [ACE plugin](/plugins/ace/) can have a maximum of 1,000 operations. * API Packages have a per-request PATCH limit of 100. + + - header: + type: h2 + text: "Apply plugins to applications {% new_in 3.15 %}" + columns: + - blocks: + - type: structured_text + config: + blocks: + - type: text + text: | + You can apply {{site.base_gateway}} plugins to your 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. + + The following table shows common use cases for applying plugins to applications: + + {% table %} + columns: + - title: Use case + key: use_case + - title: Plugin + key: plugin + rows: + - use_case: "Enforce request quotas on the credentials an application uses." + plugin: "[Rate Limiting](/plugins/rate-limiting/) or [Rate Limiting Advanced](/plugins/rate-limiting-advanced/)" + - use_case: "Ensure only requests from a partner's known IP ranges can use their application credentials." + plugin: "[IP Restriction](/plugins/ip-restriction/)" + - use_case: "Automatically inject a header identifying the partner into every request their application makes, so your upstream can route or log by customer without trusting client-supplied headers." + plugin: "[Request Transformer](/plugins/request-transformer/)" + {% endtable %} + + When a developer creates an application, Dev Portal automatically creates Kong Identity principals for 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. + * **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. + - header: + type: h3 + text: "Map an application to a Consumer" + columns: + - blocks: + - type: structured_text + config: + blocks: + - type: text + text: | + 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. + + To map an application to an existing Consumer, send a `PUT` request to the registration's `consumer` endpoint with the ID of the Gateway Consumer: + + + ```sh + curl -X PUT "https://us.api.konghq.com/v3/portals/$PORTAL_ID/applications/$APPLICATION_ID/registrations/$REGISTRATION_ID/consumer" \ + -H "Authorization: Bearer $KONNECT_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"id": "$CONSUMER_ID"}' + ``` + + + + + 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 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. + - header: type: h2 text: "Learn more" From 73a3e95ab242dabd39ccfabf0dae6294bc516cad Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 9 Jun 2026 08:51:59 -0500 Subject: [PATCH 2/7] Dev portal variable, caching infos Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_includes/dev-portal/kaa-vs-ace.md | 4 +- app/_includes/plugins/ace/ace-overview.md | 6 +- .../dev-portal/self-service.yaml | 81 ++++++++++--------- 3 files changed, 48 insertions(+), 43 deletions(-) diff --git a/app/_includes/dev-portal/kaa-vs-ace.md b/app/_includes/dev-portal/kaa-vs-ace.md index fe1668bf3f..99e9942ff4 100644 --- a/app/_includes/dev-portal/kaa-vs-ace.md +++ b/app/_includes/dev-portal/kaa-vs-ace.md @@ -5,7 +5,9 @@ When you link an API to a Gateway, you have two options: 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 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. +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. +Principal lookups are cached, so additional lookups aren't required until the cache is evicted. +Cache eviction is controlled at the principal and {{site.base_gateway}}-level. The following table can help you decide which option to pick: diff --git a/app/_includes/plugins/ace/ace-overview.md b/app/_includes/plugins/ace/ace-overview.md index cc991e35c2..5afdca9080 100644 --- a/app/_includes/plugins/ace/ace-overview.md +++ b/app/_includes/plugins/ace/ace-overview.md @@ -1,10 +1,12 @@ -The Access Control Enforcement (ACE) plugin manages developer access control to APIs published with Dev Portal. +The Access Control Enforcement (ACE) plugin manages developer access control to APIs published with {{site.dev_portal}}. You can use the ACE plugin as an alternative to the {{site.konnect_short_name}} application auth (KAA) plugin to link APIs to a Gateway instead of linking APIs to a Gateway Service. 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 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. +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. +Principal lookups are cached, so additional lookups aren't required until the cache is evicted. +Cache eviction is controlled at the principal and {{site.base_gateway}}-level. 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. diff --git a/app/_landing_pages/dev-portal/self-service.yaml b/app/_landing_pages/dev-portal/self-service.yaml index 3379fbfe05..836af4a8a3 100644 --- a/app/_landing_pages/dev-portal/self-service.yaml +++ b/app/_landing_pages/dev-portal/self-service.yaml @@ -24,11 +24,11 @@ rows: blocks: - type: text text: | - {{site.konnect_short_name}} Dev Portal provides flexible options for controlling access to content and APIs. - When combined with a [Gateway Service](/gateway/entities/service/), developers visiting a Dev Portal can sign up, create an application, register it with an API, and retrieve API keys without intervention from Dev Portal administrators. + {{site.konnect_short_name}} {{site.dev_portal}} provides flexible options for controlling access to content and APIs. + When combined with a [Gateway Service](/gateway/entities/service/), developers visiting a {{site.dev_portal}} can sign up, create an application, register it with an API, and retrieve API keys without intervention from {{site.dev_portal}} administrators. Developer self-service consists of two main components: - * **User authentication:** Allows users to access your Dev Portal by logging in. You can further customize what logged in users can see using RBAC. + * **User authentication:** Allows users to access your {{site.dev_portal}} by logging in. You can further customize what logged in users can see using RBAC. * **Application registration:** Allows developers to use your APIs using credentials and create applications for them. - header: @@ -42,18 +42,18 @@ rows: - type: text text: | To enable developer self-service, do the following: - 1. Enable user authentication by navigating to **Settings > Security** in your Dev Portal. + 1. Enable user authentication by navigating to **Settings > Security** in your {{site.dev_portal}}. - Developer sign ups and application creation require admin approval by default, which can also be configured in the Dev Portal security settings. + Developer sign ups and application creation require admin approval by default, which can also be configured in the {{site.dev_portal}} security settings. - For private Dev Portals, user authentication is enabled by default, and the default application auth strategy is key authentication. + For private {{site.dev_portal}}s, user authentication is enabled by default, and the default application auth strategy is key authentication. 1. Configure an [application authentication strategy](/dev-portal/auth-strategies/) by navigating to **Settings > Security**. - 1. Optional: Enable [application sharing](#share-applications-with-a-team) for developer teams by navigating to your Dev Portal in {{site.konnect_short_name}} and going to **Access and approvals > Teams**. Click the team, go to **Settings** and enable **Allow team to own applications**. + 1. Optional: Enable [application sharing](#share-applications-with-a-team) for developer teams by navigating to your {{site.dev_portal}} in {{site.konnect_short_name}} and going to **Access and approvals > Teams**. Click the team, go to **Settings** and enable **Allow team to own applications**. 1. Link an [API to a Gateway Service](/catalog/apis/#gateway-service-link). This is required to enforce auth strategies. - 1. Publish an [API to a Dev Portal](/catalog/apis/#publish-your-api-to-dev-portal). - 1. Select an authentication strategy when publishing the API to a Dev Portal. + 1. Publish an [API to a {{site.dev_portal}}](/catalog/apis/#publish-your-api-to-dev-portal). + 1. Select an authentication strategy when publishing the API to a {{site.dev_portal}}. 1. For public content with restricted access, use [visibility settings](/dev-portal/pages-and-content/#page-visibility-and-publishing) to show public pages or APIs to anonymous users while restricting actions to logged-in users. - header: type: h2 @@ -65,16 +65,16 @@ rows: blocks: - type: text text: | - Enabling user authentication requires users to register with the Dev Portal. + Enabling user authentication requires users to register with the {{site.dev_portal}}. You can decide which pages remain public and which ones require authentication. - Dev Portal supports the following user authentication types: + {{site.dev_portal}} supports the following user authentication types: * Basic authentication * OIDC * SAML - Additionally, you can enable [RBAC](/dev-portal/developer-rbac/) from your Dev Portal's security settings to control who can view or view and consume APIs in your Dev Portal. - When RBAC is enabled, any Dev Portal teams and roles you apply to a developer will control their access. + Additionally, you can enable [RBAC](/dev-portal/developer-rbac/) from your {{site.dev_portal}}'s security settings to control who can view or view and consume APIs in your {{site.dev_portal}}. + When RBAC is enabled, any {{site.dev_portal}} teams and roles you apply to a developer will control their access. - header: type: h3 text: "Get started with user authentication" @@ -82,27 +82,27 @@ rows: - blocks: - type: card config: - title: Configure Dev Portal SSO + title: Configure {{site.dev_portal}} SSO description: | - Set up SSO for the {{site.konnect_short_name}} Dev Portal using OpenID Connect (OIDC) or SAML. + Set up SSO for the {{site.konnect_short_name}} {{site.dev_portal}} using OpenID Connect (OIDC) or SAML. icon: /assets/icons/lock.svg cta: url: /dev-portal/sso/ - blocks: - type: card config: - title: Dev Portal IdP team mappings + title: "{{site.dev_portal}} IdP team mappings" description: | - Map existing developer teams from a third-party identity provider (IdP) and their permissions to elements in a {{site.konnect_short_name}} Dev Portal. + Map existing developer teams from a third-party identity provider (IdP) and their permissions to elements in a {{site.konnect_short_name}} {{site.dev_portal}}. icon: /assets/icons/team.svg cta: url: /dev-portal/team-mapping/ - blocks: - type: card config: - title: Dev Portal RBAC + title: "{{site.dev_portal}} RBAC" description: | - Learn about Dev Portal pre-defined teams and roles for RBAC. + Learn about {{site.dev_portal}} pre-defined teams and roles for RBAC. icon: /assets/icons/rbac.svg cta: url: /dev-portal/developer-rbac/ @@ -118,12 +118,12 @@ rows: - type: text text: | Application authentication allows developers to authenticate with your API using credentials. - Developers use the credentials from the authentication strategy when they use an API from your Dev Portal. - You can define and reuse multiple authentication strategies for different APIs and Dev Portals. + Developers use the credentials from the authentication strategy when they use an API from your {{site.dev_portal}}. + You can define and reuse multiple authentication strategies for different APIs and {{site.dev_portal}}s. - When you select an [authentication strategy](/dev-portal/auth-strategies/) during [API publication](/catalog/apis/) to a Dev Portal, {{site.konnect_short_name}} automatically applies the strategy to the linked Gateway Service. + When you select an [authentication strategy](/dev-portal/auth-strategies/) during [API publication](/catalog/apis/) to a {{site.dev_portal}}, {{site.konnect_short_name}} automatically applies the strategy to the linked Gateway Service. - Dev Portal supports the following authentication strategies: + {{site.dev_portal}} supports the following authentication strategies: * [Key authentication (`key-auth`)](/dev-portal/auth-strategies/#configure-the-key-auth-strategy) * [OpenID Connect (`oidc`)](/dev-portal/auth-strategies/#dev-portal-oidc-authentication) * [Dynamic Client Registration (DCR)](/dev-portal/dynamic-client-registration/) @@ -139,7 +139,7 @@ rows: config: title: Okta description: | - Automatically create Dev Portal applications in Okta with Dynamic Client Registration + Automatically create {{site.dev_portal}} applications in Okta with Dynamic Client Registration icon: /assets/icons/okta.svg cta: url: /how-to/okta-dcr/ @@ -148,7 +148,7 @@ rows: config: title: Azure AD description: | - Automatically create and manage Dev Portal applications in Azure AD with Dynamic Client Registration + Automatically create and manage {{site.dev_portal}} applications in Azure AD with Dynamic Client Registration icon: /assets/icons/azure.svg cta: url: /how-to/azure-ad-dcr/ @@ -157,7 +157,7 @@ rows: config: title: Auth0 description: | - Automatically create and manage Dev Portal applications in Auth0 with Dynamic Client Registration + Automatically create and manage {{site.dev_portal}} applications in Auth0 with Dynamic Client Registration icon: /assets/icons/third-party/auth0.svg cta: url: /how-to/auth0-dcr/ @@ -166,7 +166,7 @@ rows: config: title: Curity description: | - Automatically create and manage Dev Portal applications in Curity with Dynamic Client Registration + Automatically create and manage {{site.dev_portal}} applications in Curity with Dynamic Client Registration icon: /assets/icons/third-party/curity.svg cta: url: /how-to/curity-dcr/ @@ -182,7 +182,7 @@ rows: blocks: - type: text text: | - You can choose to auto approve developers and applications or require admin approval for developers and applications by navigating to **Settings** and the **Security** tab in your Dev Portal settings. + You can choose to auto approve developers and applications or require admin approval for developers and applications by navigating to **Settings** and the **Security** tab in your {{site.dev_portal}} settings. If your settings require developer or application approval, you can manage approvals by navigating to **Access and approvals** in the sidebar. You need the [API Registration Approver and Portal Viewer role](/konnect-platform/teams-and-roles/#dev-portal) assigned to the Teams that control the APIs to approve these. Additionally, you can add developers to teams by clicking on the settings menu next to the name of the developer. @@ -203,8 +203,8 @@ rows: text: | You can assign an application to a team so that all members of that team share ownership of the application. Any team member can edit, manage, and use the application. - Apps shared by a team appear in each member's apps in the Dev Portal. - Team membership and roles are managed via [Dev Portal teams and roles](/dev-portal/developer-rbac/). + Apps shared by a team appear in each member's apps in the {{site.dev_portal}}. + Team membership and roles are managed via [{{site.dev_portal}} teams and roles](/dev-portal/developer-rbac/). This is useful in cases such as when a developer leaves your organization. With team application sharing, the team retains uninterrupted access to the application. @@ -215,11 +215,11 @@ rows: Similarly, you can only register APIs to team-owned applications if everyone in the team has access to the API. This is true even if an individual team member has broader access through other teams. - To enable team application sharing, navigate to your Dev Portal in {{site.konnect_short_name}} and click **Access and approvals > Teams**. Click the relevant team, go to **Settings**, and enable **Allow team to own applications**. + To enable team application sharing, navigate to your {{site.dev_portal}} in {{site.konnect_short_name}} and click **Access and approvals > Teams**. Click the relevant team, go to **Settings**, and enable **Allow team to own applications**. To transfer ownership of an application to either a developer or team, navigate to the app and from the **Actions** dropdown menu, select "Transfer ownership". - For more information about how to configure Dev Portal developer teams, see [Dev Portal RBAC](/dev-portal/developer-rbac/). - For more information about the developer experience, see [Dev Portal developer sign-up](/dev-portal/developer-signup/#2-create-an-application). + For more information about how to configure {{site.dev_portal}} developer teams, see [{{site.dev_portal}} RBAC](/dev-portal/developer-rbac/). + For more information about the developer experience, see [{{site.dev_portal}} developer sign-up](/dev-portal/developer-signup/#2-create-an-application). - header: type: h3 text: "Limitations" @@ -246,7 +246,7 @@ rows: blocks: - type: text text: | - You can apply {{site.base_gateway}} plugins to your Dev Portal applications. + 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. The following table shows common use cases for applying plugins to applications: @@ -266,7 +266,7 @@ rows: plugin: "[Request Transformer](/plugins/request-transformer/)" {% endtable %} - When a developer creates an application, Dev Portal automatically creates Kong Identity principals for the application. + When a developer creates an application, {{site.dev_portal}} automatically creates Kong Identity principals for 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. @@ -300,9 +300,10 @@ rows: 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 Dev Portal does not validate that the Consumer exists on the Gateway. + * 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. - header: type: h2 @@ -311,9 +312,9 @@ rows: - blocks: - type: card config: - title: Dev Portal developer sign-up + title: "{{site.dev_portal}} developer sign-up" description: | - Learn how developers can get started with the Dev Portal by registering and creating an application. + Learn how developers can get started with the {{site.dev_portal}} by registering and creating an application. cta: url: /dev-portal/developer-signup/ - blocks: @@ -321,13 +322,13 @@ rows: config: title: Application authentication strategies description: | - Learn how to set up authentication strategies for application registration in Dev Portal. + Learn how to set up authentication strategies for application registration in {{site.dev_portal}}. cta: url: /dev-portal/auth-strategies/ - blocks: - type: card config: - title: Dev Portal Dynamic Client Registration + title: "{{site.dev_portal}} Dynamic Client Registration" description: | Learn about supported DCR identity providers and supported DCR authentication methods. cta: From 234c5ee6270b8d9483dc30ed9373a9f32de64e35 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 9 Jun 2026 12:24:48 -0500 Subject: [PATCH 3/7] UI step for link consumer, API steps for principal/plugin link, convert yaml to md Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- .../dev-portal/self-service.yaml | 347 ------------------ app/dev-portal/self-service.md | 261 +++++++++++++ 2 files changed, 261 insertions(+), 347 deletions(-) delete mode 100644 app/_landing_pages/dev-portal/self-service.yaml create mode 100644 app/dev-portal/self-service.md diff --git a/app/_landing_pages/dev-portal/self-service.yaml b/app/_landing_pages/dev-portal/self-service.yaml deleted file mode 100644 index 836af4a8a3..0000000000 --- a/app/_landing_pages/dev-portal/self-service.yaml +++ /dev/null @@ -1,347 +0,0 @@ -metadata: - title: "Developer self-service" - content_type: landing_page - description: "Enable self-service registration flows for developers and applications using authentication strategies and {{site.konnect_short_name}} application auth." - products: - - dev-portal - tags: - - application-registration - - authentication - breadcrumbs: - - /dev-portal/ - -rows: - - - header: - type: h1 - text: "Developer self-service and application registration" - sub_text: Enable self-service registration flows for developers and applications using authentication strategies and {{site.konnect_short_name}} application auth. - - - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - {{site.konnect_short_name}} {{site.dev_portal}} provides flexible options for controlling access to content and APIs. - When combined with a [Gateway Service](/gateway/entities/service/), developers visiting a {{site.dev_portal}} can sign up, create an application, register it with an API, and retrieve API keys without intervention from {{site.dev_portal}} administrators. - - Developer self-service consists of two main components: - * **User authentication:** Allows users to access your {{site.dev_portal}} by logging in. You can further customize what logged in users can see using RBAC. - * **Application registration:** Allows developers to use your APIs using credentials and create applications for them. - - - header: - type: h2 - text: "Enable developer self-service" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - To enable developer self-service, do the following: - 1. Enable user authentication by navigating to **Settings > Security** in your {{site.dev_portal}}. - - Developer sign ups and application creation require admin approval by default, which can also be configured in the {{site.dev_portal}} security settings. - - For private {{site.dev_portal}}s, user authentication is enabled by default, and the default application auth strategy is key authentication. - 1. Configure an [application authentication strategy](/dev-portal/auth-strategies/) by navigating to **Settings > Security**. - 1. Optional: Enable [application sharing](#share-applications-with-a-team) for developer teams by navigating to your {{site.dev_portal}} in {{site.konnect_short_name}} and going to **Access and approvals > Teams**. Click the team, go to **Settings** and enable **Allow team to own applications**. - 1. Link an [API to a Gateway Service](/catalog/apis/#gateway-service-link). - - This is required to enforce auth strategies. - 1. Publish an [API to a {{site.dev_portal}}](/catalog/apis/#publish-your-api-to-dev-portal). - 1. Select an authentication strategy when publishing the API to a {{site.dev_portal}}. - 1. For public content with restricted access, use [visibility settings](/dev-portal/pages-and-content/#page-visibility-and-publishing) to show public pages or APIs to anonymous users while restricting actions to logged-in users. - - header: - type: h2 - text: "User authentication" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - Enabling user authentication requires users to register with the {{site.dev_portal}}. - You can decide which pages remain public and which ones require authentication. - - {{site.dev_portal}} supports the following user authentication types: - * Basic authentication - * OIDC - * SAML - - Additionally, you can enable [RBAC](/dev-portal/developer-rbac/) from your {{site.dev_portal}}'s security settings to control who can view or view and consume APIs in your {{site.dev_portal}}. - When RBAC is enabled, any {{site.dev_portal}} teams and roles you apply to a developer will control their access. - - header: - type: h3 - text: "Get started with user authentication" - columns: - - blocks: - - type: card - config: - title: Configure {{site.dev_portal}} SSO - description: | - Set up SSO for the {{site.konnect_short_name}} {{site.dev_portal}} using OpenID Connect (OIDC) or SAML. - icon: /assets/icons/lock.svg - cta: - url: /dev-portal/sso/ - - blocks: - - type: card - config: - title: "{{site.dev_portal}} IdP team mappings" - description: | - Map existing developer teams from a third-party identity provider (IdP) and their permissions to elements in a {{site.konnect_short_name}} {{site.dev_portal}}. - icon: /assets/icons/team.svg - cta: - url: /dev-portal/team-mapping/ - - blocks: - - type: card - config: - title: "{{site.dev_portal}} RBAC" - description: | - Learn about {{site.dev_portal}} pre-defined teams and roles for RBAC. - icon: /assets/icons/rbac.svg - cta: - url: /dev-portal/developer-rbac/ - - - header: - type: h2 - text: "Application authentication strategies" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - Application authentication allows developers to authenticate with your API using credentials. - Developers use the credentials from the authentication strategy when they use an API from your {{site.dev_portal}}. - You can define and reuse multiple authentication strategies for different APIs and {{site.dev_portal}}s. - - When you select an [authentication strategy](/dev-portal/auth-strategies/) during [API publication](/catalog/apis/) to a {{site.dev_portal}}, {{site.konnect_short_name}} automatically applies the strategy to the linked Gateway Service. - - {{site.dev_portal}} supports the following authentication strategies: - * [Key authentication (`key-auth`)](/dev-portal/auth-strategies/#configure-the-key-auth-strategy) - * [OpenID Connect (`oidc`)](/dev-portal/auth-strategies/#dev-portal-oidc-authentication) - * [Dynamic Client Registration (DCR)](/dev-portal/dynamic-client-registration/) - - If a Gateway Service isn't associated with the API when you choose an authentication strategy, the settings are saved and applied once a Service is linked. - If a Service is later unlinked, the authentication strategy is applied to the next linked Service. - - header: - type: h3 - text: "Get started with Dynamic Client Registration" - columns: - - blocks: - - type: card - config: - title: Okta - description: | - Automatically create {{site.dev_portal}} applications in Okta with Dynamic Client Registration - icon: /assets/icons/okta.svg - cta: - url: /how-to/okta-dcr/ - - blocks: - - type: card - config: - title: Azure AD - description: | - Automatically create and manage {{site.dev_portal}} applications in Azure AD with Dynamic Client Registration - icon: /assets/icons/azure.svg - cta: - url: /how-to/azure-ad-dcr/ - - blocks: - - type: card - config: - title: Auth0 - description: | - Automatically create and manage {{site.dev_portal}} applications in Auth0 with Dynamic Client Registration - icon: /assets/icons/third-party/auth0.svg - cta: - url: /how-to/auth0-dcr/ - - blocks: - - type: card - config: - title: Curity - description: | - Automatically create and manage {{site.dev_portal}} applications in Curity with Dynamic Client Registration - icon: /assets/icons/third-party/curity.svg - cta: - url: /how-to/curity-dcr/ - - - - header: - type: h2 - text: "Developer and application approvals" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - You can choose to auto approve developers and applications or require admin approval for developers and applications by navigating to **Settings** and the **Security** tab in your {{site.dev_portal}} settings. - - If your settings require developer or application approval, you can manage approvals by navigating to **Access and approvals** in the sidebar. You need the [API Registration Approver and Portal Viewer role](/konnect-platform/teams-and-roles/#dev-portal) assigned to the Teams that control the APIs to approve these. - Additionally, you can add developers to teams by clicking on the settings menu next to the name of the developer. - - Once approved, developers can create applications and view APIs, and the application can generate credentials to use the APIs. - - Applications and API keys are specific to a [geographic region](/konnect-platform/geos/). - When you enable application registration by selecting an authentication strategy during publication, the resulting applications and API keys are tied to the developers and traffic in that region. - - header: - type: h3 - text: "Share applications with a team" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - You can assign an application to a team so that all members of that team share ownership of the application. - Any team member can edit, manage, and use the application. - Apps shared by a team appear in each member's apps in the {{site.dev_portal}}. - Team membership and roles are managed via [{{site.dev_portal}} teams and roles](/dev-portal/developer-rbac/). - - This is useful in cases such as when a developer leaves your organization. - With team application sharing, the team retains uninterrupted access to the application. - - Important considerations: - * All members of the team that owns an application receive full ownership access. - * Applications can only be transferred to teams that have [API Consumer](/dev-portal/developer-rbac/) access for every API currently registered by the application. - Similarly, you can only register APIs to team-owned applications if everyone in the team has access to the API. - This is true even if an individual team member has broader access through other teams. - - To enable team application sharing, navigate to your {{site.dev_portal}} in {{site.konnect_short_name}} and click **Access and approvals > Teams**. Click the relevant team, go to **Settings**, and enable **Allow team to own applications**. - To transfer ownership of an application to either a developer or team, navigate to the app and from the **Actions** dropdown menu, select "Transfer ownership". - - For more information about how to configure {{site.dev_portal}} developer teams, see [{{site.dev_portal}} RBAC](/dev-portal/developer-rbac/). - For more information about the developer experience, see [{{site.dev_portal}} developer sign-up](/dev-portal/developer-signup/#2-create-an-application). - - header: - type: h3 - text: "Limitations" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - Keep the following limitations in mind for developers and applications: - * Each developer can create a maximum of 500 applications. - * Each application can have a maximum of 20 API keys. - * Each API that uses the [ACE plugin](/plugins/ace/) can have a maximum of 1,000 operations. - * API Packages have a per-request PATCH limit of 100. - - - header: - type: h2 - text: "Apply plugins to applications {% new_in 3.15 %}" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - 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. - - The following table shows common use cases for applying plugins to applications: - - {% table %} - columns: - - title: Use case - key: use_case - - title: Plugin - key: plugin - rows: - - use_case: "Enforce request quotas on the credentials an application uses." - plugin: "[Rate Limiting](/plugins/rate-limiting/) or [Rate Limiting Advanced](/plugins/rate-limiting-advanced/)" - - use_case: "Ensure only requests from a partner's known IP ranges can use their application credentials." - plugin: "[IP Restriction](/plugins/ip-restriction/)" - - use_case: "Automatically inject a header identifying the partner into every request their application makes, so your upstream can route or log by customer without trusting client-supplied headers." - plugin: "[Request Transformer](/plugins/request-transformer/)" - {% endtable %} - - When a developer creates an application, {{site.dev_portal}} automatically creates Kong Identity principals for 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. - * **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. - - - header: - type: h3 - text: "Map an application to a Consumer" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - 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. - - To map an application to an existing Consumer, send a `PUT` request to the registration's `consumer` endpoint with the ID of the Gateway Consumer: - - - ```sh - curl -X PUT "https://us.api.konghq.com/v3/portals/$PORTAL_ID/applications/$APPLICATION_ID/registrations/$REGISTRATION_ID/consumer" \ - -H "Authorization: Bearer $KONNECT_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"id": "$CONSUMER_ID"}' - ``` - - - - - 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. - * 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. - - - header: - type: h2 - text: "Learn more" - columns: - - blocks: - - type: card - config: - title: "{{site.dev_portal}} developer sign-up" - description: | - Learn how developers can get started with the {{site.dev_portal}} by registering and creating an application. - cta: - url: /dev-portal/developer-signup/ - - blocks: - - type: card - config: - title: Application authentication strategies - description: | - Learn how to set up authentication strategies for application registration in {{site.dev_portal}}. - cta: - url: /dev-portal/auth-strategies/ - - blocks: - - type: card - config: - title: "{{site.dev_portal}} Dynamic Client Registration" - description: | - Learn about supported DCR identity providers and supported DCR authentication methods. - cta: - url: /dev-portal/dynamic-client-registration/ - - - header: - text: "Frequently asked questions" - type: h2 - columns: - - blocks: - - type: faqs - config: - - q: | - {% include faqs/api-app-reg-override.md section='question' %} - a: | - {% include faqs/api-app-reg-override.md section='answer' %} \ No newline at end of file diff --git a/app/dev-portal/self-service.md b/app/dev-portal/self-service.md new file mode 100644 index 0000000000..c8fe957c20 --- /dev/null +++ b/app/dev-portal/self-service.md @@ -0,0 +1,261 @@ +--- +title: "Developer self-service and application registration" +content_type: reference +layout: reference + +products: + - dev-portal +tags: + - application-registration + - authentication + +works_on: + - konnect + +breadcrumbs: + - /dev-portal/ + +api_specs: + - konnect/portal-management + +description: "Enable self-service registration flows for developers and applications using authentication strategies and {{site.konnect_short_name}} application auth." + +related_resources: + - text: "{{site.dev_portal}} developer sign-up" + url: /dev-portal/developer-signup/ + - text: Application authentication strategies + url: /dev-portal/auth-strategies/ + - text: "{{site.dev_portal}} Dynamic Client Registration" + url: /dev-portal/dynamic-client-registration/ + +faqs: + - q: | + {% include faqs/api-app-reg-override.md section='question' %} + a: | + {% include faqs/api-app-reg-override.md section='answer' %} +--- + +{{site.konnect_short_name}} {{site.dev_portal}} provides flexible options for controlling access to content and APIs. +When combined with a [Gateway Service](/gateway/entities/service/), developers visiting a {{site.dev_portal}} can sign up, create an application, register it with an API, and retrieve API keys without intervention from {{site.dev_portal}} administrators. + +Developer self-service consists of two main components: +* **User authentication:** Allows users to access your {{site.dev_portal}} by logging in. You can further customize what logged in users can see using RBAC. +* **Application registration:** Allows developers to use your APIs using credentials and create applications for them. + +## Enable developer self-service + +To enable developer self-service, do the following: +1. Enable user authentication by navigating to **Settings > Security** in your {{site.dev_portal}}. + + Developer sign ups and application creation require admin approval by default, which can also be configured in the {{site.dev_portal}} security settings. + + For private {{site.dev_portal}}s, user authentication is enabled by default, and the default application auth strategy is key authentication. +1. Configure an [application authentication strategy](/dev-portal/auth-strategies/) by navigating to **Settings > Security**. +1. Optional: Enable [application sharing](#share-applications-with-a-team) for developer teams by navigating to your {{site.dev_portal}} in {{site.konnect_short_name}} and going to **Access and approvals > Teams**. Click the team, go to **Settings** and enable **Allow team to own applications**. +1. Link an [API to a Gateway Service](/catalog/apis/#gateway-service-link). + + This is required to enforce auth strategies. +1. Publish an [API to a {{site.dev_portal}}](/catalog/apis/#publish-your-api-to-dev-portal). +1. Select an authentication strategy when publishing the API to a {{site.dev_portal}}. +1. For public content with restricted access, use [visibility settings](/dev-portal/pages-and-content/#page-visibility-and-publishing) to show public pages or APIs to anonymous users while restricting actions to logged-in users. + +## User authentication + +Enabling user authentication requires users to register with the {{site.dev_portal}}. +You can decide which pages remain public and which ones require authentication. + +{{site.dev_portal}} supports the following user authentication types: +* Basic authentication +* OIDC +* SAML + +Additionally, you can enable [RBAC](/dev-portal/developer-rbac/) from your {{site.dev_portal}}'s security settings to control who can view or view and consume APIs in your {{site.dev_portal}}. +When RBAC is enabled, any {{site.dev_portal}} teams and roles you apply to a developer will control their access. + +To get started with user authentication, see the following how-tos: +* [Configure {{site.dev_portal}} SSO](/dev-portal/sso/) +* [{{site.dev_portal}} IdP team mappings](/dev-portal/team-mapping/) +* [{{site.dev_portal}} RBAC](/dev-portal/developer-rbac/) + +## Application authentication strategies + +Application authentication allows developers to authenticate with your API using credentials. +Developers use the credentials from the authentication strategy when they use an API from your {{site.dev_portal}}. +You can define and reuse multiple authentication strategies for different APIs and {{site.dev_portal}}s. + +When you select an [authentication strategy](/dev-portal/auth-strategies/) during [API publication](/catalog/apis/) to a {{site.dev_portal}}, {{site.konnect_short_name}} automatically applies the strategy to the linked Gateway Service. + +{{site.dev_portal}} supports the following authentication strategies: +* [Key authentication (`key-auth`)](/dev-portal/auth-strategies/#configure-the-key-auth-strategy) +* [OpenID Connect (`oidc`)](/dev-portal/auth-strategies/#dev-portal-oidc-authentication) +* [Dynamic Client Registration (DCR)](/dev-portal/dynamic-client-registration/) + +If a Gateway Service isn't associated with the API when you choose an authentication strategy, the settings are saved and applied once a Service is linked. +If a Service is later unlinked, the authentication strategy is applied to the next linked Service. + +To automatically create and manage {{site.dev_portal}} applications using Dynamic Client Registration, see the following guides: + +{% html_tag type="div" css_classes="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-3" %} +{% icon_card icon="okta.svg" title="Okta" cta_url="/how-to/okta-dcr/" %} +{% icon_card icon="azure.svg" title="Azure AD" cta_url="/how-to/azure-ad-dcr/" %} +{% icon_card icon="third-party/auth0.svg" title="Auth0" cta_url="/how-to/auth0-dcr/" %} +{% icon_card icon="third-party/curity.svg" title="Curity" cta_url="/how-to/curity-dcr/" %} +{% endhtml_tag %} + +## Developer and application approvals + +You can choose to auto approve developers and applications or require admin approval for developers and applications by navigating to **Settings** and the **Security** tab in your {{site.dev_portal}} settings. + +If your settings require developer or application approval, you can manage approvals by navigating to **Access and approvals** in the sidebar. You need the [API Registration Approver and Portal Viewer role](/konnect-platform/teams-and-roles/#dev-portal) assigned to the Teams that control the APIs to approve these. +Additionally, you can add developers to teams by clicking on the settings menu next to the name of the developer. + +Once approved, developers can create applications and view APIs, and the application can generate credentials to use the APIs. + +Applications and API keys are specific to a [geographic region](/konnect-platform/geos/). +When you enable application registration by selecting an authentication strategy during publication, the resulting applications and API keys are tied to the developers and traffic in that region. + +### Share applications with a team + +You can assign an application to a team so that all members of that team share ownership of the application. +Any team member can edit, manage, and use the application. +Apps shared by a team appear in each member's apps in the {{site.dev_portal}}. +Team membership and roles are managed via [{{site.dev_portal}} teams and roles](/dev-portal/developer-rbac/). + +This is useful in cases such as when a developer leaves your organization. +With team application sharing, the team retains uninterrupted access to the application. + +Important considerations: +* All members of the team that owns an application receive full ownership access. +* Applications can only be transferred to teams that have [API Consumer](/dev-portal/developer-rbac/) access for every API currently registered by the application. + Similarly, you can only register APIs to team-owned applications if everyone in the team has access to the API. + This is true even if an individual team member has broader access through other teams. + +To enable team application sharing, navigate to your {{site.dev_portal}} in {{site.konnect_short_name}} and click **Access and approvals > Teams**. Click the relevant team, go to **Settings**, and enable **Allow team to own applications**. +To transfer ownership of an application to either a developer or team, navigate to the app and from the **Actions** dropdown menu, select "Transfer ownership". + +For more information about how to configure {{site.dev_portal}} developer teams, see [{{site.dev_portal}} RBAC](/dev-portal/developer-rbac/). +For more information about the developer experience, see [{{site.dev_portal}} developer sign-up](/dev-portal/developer-signup/#2-create-an-application). + +### Limitations + +Keep the following limitations in mind for developers and applications: +* Each developer can create a maximum of 500 applications. +* Each application can have a maximum of 20 API keys. +* Each API that uses the [ACE plugin](/plugins/ace/) can have a maximum of 1,000 operations. +* API Packages have a per-request PATCH limit of 100. + +## 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. + +The following table shows common use cases for applying plugins to applications: + + +{% table %} +columns: + - title: Use case + key: use_case + - title: Plugin + key: plugin +rows: + - use_case: "Enforce request quotas on the credentials an application uses." + plugin: "[Rate Limiting](/plugins/rate-limiting/) or [Rate Limiting Advanced](/plugins/rate-limiting-advanced/)" + - use_case: "Ensure only requests from a partner's known IP ranges can use their application credentials." + plugin: "[IP Restriction](/plugins/ip-restriction/)" + - use_case: "Automatically inject a header identifying the partner into every request their application makes, so your upstream can route or log by customer without trusting client-supplied headers." + plugin: "[Request Transformer](/plugins/request-transformer/)" +{% endtable %} + + +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. +* **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 + +We recommend this method because it applies the plugin based on the application's principal, without requiring you to map the application to a Gateway Consumer. +The plugin runs whenever a request authenticates as that application, using a [conditional plugin execution](/gateway/configure-conditional-plugin-execution/) expression that references the application's `principal.id`. + +In this example, we'll use the [Rate Limiting Advanced](/plugins/rate-limiting-advanced/) plugin, but you can apply any plugin to an application's principal with `principal.id`. + +1. List the applications in your portal and capture the application's principal ID as the `PRINCIPAL_ID` variable: + +{% konnect_api_request %} +url: /v3/portals/$PORTAL_ID/applications +status_code: 200 +region: us +method: GET +capture: + - variable: PRINCIPAL_ID + jq: '.data[0].principal_id' +{% endkonnect_api_request %} + +1. Configure the Rate Limiting Advanced plugin and use a conditional plugin execution expression to apply it to the application's principal. Replace `$CONTROL_PLANE_ID` with the ID of the control plane that your API is linked to: + +{% konnect_api_request %} +url: /v2/control-planes/$CONTROL_PLANE_ID/core-entities/plugins/ +status_code: 201 +region: us +method: POST +body: + name: rate-limiting-advanced + config: + limit: + - 200 + window_size: + - 1800 + window_type: fixed + namespace: my-namespace + condition: 'principal.id == "$PRINCIPAL_ID"' +{% endkonnect_api_request %} + + + +Any request that authenticates as this application is now rate limited to 200 requests every 30 minutes. + +### 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. + +{% navtabs "map-consumer" %} +{% navtab "API" %} +To map an application to an existing Consumer, send a `PUT` request to the registration's `consumer` endpoint with the ID of the Gateway Consumer: + + +{% konnect_api_request %} +url: /v3/portals/$PORTAL_ID/applications/$APPLICATION_ID/registrations/$REGISTRATION_ID/consumer +status_code: 204 +region: us +method: PUT +body: + id: $CONSUMER_ID +{% endkonnect_api_request %} + + +{% endnavtab %} +{% navtab "UI" %} +1. In the {{site.konnect_short_name}} sidebar, click **Dev Portal > Portals**. +1. Click your portal. +1. Click the **Access and approvals** tab. +1. Click the **App Registrations** tab. +1. Click the application you want to link a Consumer to. +1. In the **App Registrations** section, click the action menu icon for the registration. +1. Click **Link Consumer**. +1. From the **Consumer** dropdown menu, select the Consumer you want to link. + The API must be [linked to a Gateway Service or control plane](/catalog/apis/#allow-developers-to-consume-your-api) to link a Consumer. +1. Click **Link consumer**. +{% endnavtab %} +{% endnavtabs %} + +Any plugins that were applied to the Consumer are now applied to the {{site.dev_portal}} application. + +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. +* 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. From ebf0067788403789d216aef008b3400918936595 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Wed, 10 Jun 2026 08:46:08 -0500 Subject: [PATCH 4/7] fix principal requests Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/dev-portal/self-service.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/app/dev-portal/self-service.md b/app/dev-portal/self-service.md index c8fe957c20..ad61f6ebbe 100644 --- a/app/dev-portal/self-service.md +++ b/app/dev-portal/self-service.md @@ -181,18 +181,19 @@ The plugin runs whenever a request authenticates as that application, using a [c In this example, we'll use the [Rate Limiting Advanced](/plugins/rate-limiting-advanced/) plugin, but you can apply any plugin to an application's principal with `principal.id`. -1. List the applications in your portal and capture the application's principal ID as the `PRINCIPAL_ID` variable: +1. List the applications in your portal, filtering by the application's name, and capture its ID as the `PRINCIPAL_ID` variable. Replace `$APPLICATION_NAME` with the name of your application: {% konnect_api_request %} -url: /v3/portals/$PORTAL_ID/applications +url: /v3/portals/$PORTAL_ID/applications?filter%5Bname%5D%5Beq%5D=$APPLICATION_NAME status_code: 200 region: us method: GET capture: - variable: PRINCIPAL_ID - jq: '.data[0].principal_id' + jq: '.data[0].id' {% endkonnect_api_request %} + The principal ID is the same as the application's ID. 1. Configure the Rate Limiting Advanced plugin and use a conditional plugin execution expression to apply it to the application's principal. Replace `$CONTROL_PLANE_ID` with the ID of the control plane that your API is linked to: {% konnect_api_request %} @@ -212,7 +213,6 @@ body: condition: 'principal.id == "$PRINCIPAL_ID"' {% endkonnect_api_request %} - Any request that authenticates as this application is now rate limited to 200 requests every 30 minutes. From 70e2f9a26214db59c7e3c9df7460d2b9bc8787d5 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Wed, 10 Jun 2026 16:04:13 -0500 Subject: [PATCH 5/7] Apply PM/eng feedback Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/dev-portal/self-service.md | 38 ++++++++++++++++++++++++++++------ 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/app/dev-portal/self-service.md b/app/dev-portal/self-service.md index ad61f6ebbe..615b57395b 100644 --- a/app/dev-portal/self-service.md +++ b/app/dev-portal/self-service.md @@ -168,13 +168,37 @@ rows: {% endtable %} -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 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. 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. -* **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 + +{% table %} +columns: + - title: Method + key: method + - title: Existing Consumers for {{site.dev_portal}} applications + key: existing_consumers + - title: Plugin mapped to + key: mapped_to + - title: Description + key: description +rows: + - method: "Conditional plugin execution" + existing_consumers: "No" + mapped_to: "Principal" + description: "Use [conditional plugin execution](/gateway/configure-conditional-plugin-execution/) with an expression that references the application's `principal.id`. You can manage the principal configuration in {{site.identity}} and the plugin configuration in Gateway Manager." + - method: "Consumer-scoped plugins" + existing_consumers: "Yes" + mapped_to: "Consumer" + description: "[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." +{% endtable %} + + +### Apply a plugin to an application using a {{site.identity}} principal We recommend this method because it applies the plugin based on the application's principal, without requiring you to map the application to a Gateway Consumer. The plugin runs whenever a request authenticates as that application, using a [conditional plugin execution](/gateway/configure-conditional-plugin-execution/) expression that references the application's `principal.id`. @@ -252,10 +276,12 @@ body: Any plugins that were applied to the Consumer are now applied to the {{site.dev_portal}} application. -Keep the following in mind when you map applications to Consumers: +### Limitations + +Keep the following in mind when you map applications to Consumers or principals: * 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. +* If you're mapping applications to Consumers, the Consumer must already exist. The {{site.dev_portal}} validates that the Consumer exists on the Gateway before it will be mapped. * 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. From f1cf8cc08015202a264522ba10e395329cf3484f Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Thu, 11 Jun 2026 09:51:55 -0500 Subject: [PATCH 6/7] Adjust kaa vs ace wording Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_includes/dev-portal/kaa-vs-ace.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_includes/dev-portal/kaa-vs-ace.md b/app/_includes/dev-portal/kaa-vs-ace.md index 99e9942ff4..d4d0abb864 100644 --- a/app/_includes/dev-portal/kaa-vs-ace.md +++ b/app/_includes/dev-portal/kaa-vs-ace.md @@ -5,7 +5,7 @@ When you link an API to a Gateway, you have two options: 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. +In {{site.base_gateway}} 3.15 or later, both plugins also look up {{site.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. Principal lookups are cached, so additional lookups aren't required until the cache is evicted. Cache eviction is controlled at the principal and {{site.base_gateway}}-level. From c8011cf952da74ecc9516d086c4e5fa8481c9c20 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Thu, 11 Jun 2026 15:11:11 -0500 Subject: [PATCH 7/7] Fix section lead in Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/dev-portal/self-service.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/app/dev-portal/self-service.md b/app/dev-portal/self-service.md index 615b57395b..9586103e75 100644 --- a/app/dev-portal/self-service.md +++ b/app/dev-portal/self-service.md @@ -200,12 +200,13 @@ rows: ### Apply a plugin to an application using a {{site.identity}} principal -We recommend this method because it applies the plugin based on the application's principal, without requiring you to map the application to a Gateway Consumer. +This method applies the plugin based on the application's principal, without requiring you to map the application to a Gateway Consumer. The plugin runs whenever a request authenticates as that application, using a [conditional plugin execution](/gateway/configure-conditional-plugin-execution/) expression that references the application's `principal.id`. In this example, we'll use the [Rate Limiting Advanced](/plugins/rate-limiting-advanced/) plugin, but you can apply any plugin to an application's principal with `principal.id`. 1. List the applications in your portal, filtering by the application's name, and capture its ID as the `PRINCIPAL_ID` variable. Replace `$APPLICATION_NAME` with the name of your application: +{% capture copy-app-id %} {% konnect_api_request %} url: /v3/portals/$PORTAL_ID/applications?filter%5Bname%5D%5Beq%5D=$APPLICATION_NAME @@ -217,8 +218,11 @@ capture: jq: '.data[0].id' {% endkonnect_api_request %} +{% endcapture %} +{{ copy-app-id | indent: 3}} The principal ID is the same as the application's ID. 1. Configure the Rate Limiting Advanced plugin and use a conditional plugin execution expression to apply it to the application's principal. Replace `$CONTROL_PLANE_ID` with the ID of the control plane that your API is linked to: +{% capture apply-plugin %} {% konnect_api_request %} url: /v2/control-planes/$CONTROL_PLANE_ID/core-entities/plugins/ @@ -237,7 +241,8 @@ body: condition: 'principal.id == "$PRINCIPAL_ID"' {% endkonnect_api_request %} - +{% endcapture %} +{{ apply-plugin | indent: 3}} Any request that authenticates as this application is now rate limited to 200 requests every 30 minutes. ### Map an application to a Consumer