Skip to content
|
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 Service Hub, so you don’t need this plugin. See the following documentation:

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.

Example plugin configuration

The following examples provide some typical configurations for enabling the application-registration plugin on a service.

Make the following request:

curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/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"

Replace SERVICE_NAME|SERVICE_ID with 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_NAME|SERVICE_ID
  labels:
    app: SERVICE_NAME|SERVICE_ID
  annotations:
    konghq.com/plugins: application-registration-example
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: SERVICE_NAME|SERVICE_ID
  selector:
    app: SERVICE_NAME|SERVICE_ID

Replace SERVICE_NAME|SERVICE_ID with 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.

Add this section to your declarative configuration file:

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

Replace SERVICE_NAME|SERVICE_ID with the id or name of the service that this plugin configuration will target.

You can configure this plugin through the Kong Manager UI.

  1. In Kong Manager, select the workspace.
  2. From the Services section, click View for the service row.
  3. From the plugin section, 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 pre-filled.

  7. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

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

This plugin cannot be enabled globally. Please select another tab.

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.name or service.id
required

Type: string		 The name or ID of the service the plugin targets.

Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.

Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins.
enabled

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"