In order to give you better service we use cookies. By continuing to use our website, you agree to the use of cookies as described in our Cookie Policy

Are you a Kong Gateway user? We'd love your feedback. Take the Survey

Kong Logo
header icon

Portal Application Registration

Kong Enterprise only: This plugin is only available with a Kong Enterprise subscription. Please inquire about Kong Enterprise by contacting us, or start a free trial today.

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

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

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

Configuration Reference

You can configure this plugin using the Kong Admin API or through declarative configuration, which involves directly editing the Kong configuration file.

This plugin is compatible with requests with the following protocols:

  • http
  • https
  • grpc
  • grpcs

This plugin is not compatible with DB-less mode.

Enabling the plugin on a Service

Kong Admin API
Kubernetes
Declarative (YAML)

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

$ curl -X POST http://<admin-hostname>: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"

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>
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.

Enabling 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.

Kong Admin API
Kubernetes
Declarative (YAML)

For example, configure this plugin globally with:

$ curl -X POST http://<admin-hostname>: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

Parameters

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

Form ParameterDescription
name

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

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

Type: boolean

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

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

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

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

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"