Skip to content
Kong Gateway 2.8 Increases Security and Simplifies API Management.  —Learn More →
|
search
Plugin Hub
header icon

Portal Application Registration

Applications allow registered developers on Kong Developer Portal to authenticate against a Gateway Service. Dev Portal admins can selectively admit access to Services using the Application Registration plugin.

Note: This plugin is for application registration in self-managed Kong Gateway instances.

In Konnect, the functionality is built into the ServiceHub, so you don’t need to set up this plugin. See the Konnect Application Overview for more information.

The Application Registration plugin is used in tandem with supported Kong Gateway authorization plugins, depending on your configured Dev Portal authorization provider. Either Kong Gateway (kong-oauth2) or a third-party OAuth provider (external-oauth2) can be the system of record (SoR) for application credentials. For more information, see Configure an Authorization Provider Strategy.

To learn how to set up key authentication, see Enable Key Authentication for Application Registration.

Supported authorization plugins for use with application registration:

Kong Gateway Plugin Portal authorization strategy
OAuth2 kong-oauth2
Key Auth kong-oauth2
OIDC external-oauth2

If you plan to use the external OAuth option with OIDC, review the supported OAuth workflows.

Configuration Reference

This plugin is not compatible with DB-less mode.

Enable the plugin on a service

For example, configure this plugin on a service by making the following request:

curl -X POST http://{HOST}:8001/services/{SERVICE}/plugins \
    --data "name=application-registration"  \
    --data "config.auto_approve=false" \
    --data "config.description=<my_service_description>" \
    --data "config.display_name=<my_service_display_name>" \
    --data "config.show_issuer=false"

SERVICE is the id or name of the service that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <application-registration-example>
config: 
  auto_approve: false
  description: <my_service_description>
  display_name: <my_service_display_name>
  show_issuer: false
plugin: application-registration

Next, apply the KongPlugin resource to a Service by annotating the Service as follows:

apiVersion: v1
kind: Service
metadata:
  name: {SERVICE}
  labels:
    app: {SERVICE}
  annotations:
    konghq.com/plugins: <application-registration-example>
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: {SERVICE}
  selector:
    app: {SERVICE}

{SERVICE} is the id or name of the service that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a service by adding this section to your declarative configuration file:

plugins:
- name: application-registration
  service: {SERVICE}
  config: 
    auto_approve: false
    description: <my_service_description>
    display_name: <my_service_display_name>
    show_issuer: false

SERVICE is the id or name of the service that this plugin configuration will target.

Configure this plugin on a service:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, scroll down to Services and click View for the service row.
  3. Scroll down to plugins and click Add Plugin.

  4. Find and select the Portal Application Registration plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  5. If the option is available, select Scoped.
  6. Add the service name and ID to the Service field if it is not already prefilled.

  7. Enter the following parameters, updating the default or sample values as needed:

    • Config.Auto Approve: clear checkbox
    • Config.Display Name: <my_service_display_name>
    • Config.Show Issuer: clear checkbox
  8. Click Create.

Enable the plugin globally

A plugin which is not associated to any service, route, or consumer is considered global, and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

For example, configure this plugin globally with:

$ curl -X POST http://{HOST}:8001/plugins/ \
    --data "name=application-registration"  \
    --data "config.auto_approve=false" \
    --data "config.description=<my_service_description>" \
    --data "config.display_name=<my_service_display_name>" \
    --data "config.show_issuer=false"

Create a KongClusterPlugin resource and label it as global:

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-application-registration>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  auto_approve: false
  description: <my_service_description>
  display_name: <my_service_display_name>
  show_issuer: false
plugin: application-registration

For example, configure this plugin using the plugins: entry in the declarative configuration file:

plugins:
- name: application-registration
  config: 
    auto_approve: false
    description: <my_service_description>
    display_name: <my_service_display_name>
    show_issuer: false

Configure this plugin globally:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Plugins in the left navigation.
  3. Click New Plugin.

  4. Find and select the Portal Application Registration plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  5. If the option is available, set the plugin scope to Global.

  6. Enter the following parameters, updating the default/sample values as needed:

    • Config.Auto Approve: clear checkbox
    • Config.Display Name: <my_service_display_name>
    • Config.Show Issuer: clear checkbox
  7. Click Create.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Form Parameter Description
name
required

Type: string		 The name of the plugin, in this case application-registration.
service.id

Type: string		 The ID of the Service the plugin targets.
enabled
required

Type: boolean

Default value: true		 Whether this plugin will be applied.
config.auto_approve
required

Type: boolean

Default value: false

If enabled, all new Service Contracts requests are automatically approved. See Enable automatic registration approval. Otherwise, Dev Portal admins must manually approve requests.
config.description
optional

Type: string

Unique description displayed in information about a Service in the Developer Portal.
config.display_name
required

Type: string

Unique display name used for a Service in the Developer Portal.
config.show_issuer
required

Type: boolean

Default value: false

Displays the Issuer URL in the Service Details dialog.

Examples

Replace <DNSorIP> with your host name or IP address, {service} with your Service name, and <my_service_display_name> with the display_name of your Service for examples in this section.

Enable automatic registration approval

Enable auto_approve so that application registration requests are automatically approved.

curl -X POST http://<DNSorIP>:8001/services/{service} \
    --data "name=application-registration"  \
    --data "config.display_name=<my_service_display_name>" \
    --data "config.auto_approve=true

Update your current configuration by running a PATCH command. Replace {plugin_id} with the id of your plugin.

curl -X PATCH http://<DNSorIP>:8001/plugins/{plugin_id} \
  --data "config.auto_approve=true"

Enable show issuer URL

Enable show_issuer to expose the Issuer URL in the Service Details dialog.

Note: Exposing the Issuer URL is essential for the Authorization Code Flow configured for third-party identity providers.

Update your current configuration by running a PATCH command. Replace {plugin_id} with the id of your plugin.

curl -X PATCH http://<DNSorIP>:8001/plugins/{plugin_id} \
  --data "config.show_issuer=true"