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.
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.
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 compatible with requests with the following protocols:
This plugin is not compatible with DB-less mode.
Enable the plugin on a service
Admin API
Kubernetes
Declarative (YAML)
Manager
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:
- In Kong Manager, select the workspace.
- From the Dashboard, scroll down to Services and click View for the
service row.
- Scroll down to plugins and click Add Plugin.
-
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.
- If the option is available, select Scoped.
- Add the service name and ID to the Service field if it
is not already prefilled.
-
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
- 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.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
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:
- In Kong Manager, select the workspace.
- From the Dashboard, select Plugins in the left navigation.
- Click New Plugin.
-
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.
- If the option is available, set the plugin scope to Global.
-
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
- Click Create.
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
| Form Parameter |
Description |
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
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"
