Portal Application Registration

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

At least one OAuth2 grant flow (typical use case) must be enabled for the plugin on a Service:

• Authorization Code
• Client Credentials
• Implicit Grant
• Password Grant

Terminology

• plugin: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.
• Service: the Kong entity representing an external upstream API or microservice.
• Upstream service: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.

Configuration

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

Configure this plugin on a Service by making the following request:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=application-registration"  \
    --data "config.auth_header_name=authorization" \
    --data "config.auto_approve=false" \
    --data "config.display_name=<my_service_display_name>" \
    --data "config.enable_authorization_code=true" \
    --data "config.enable_client_credentials=true" \
    --data "config.enable_implicit_grant=true" \
    --data "config.enable_password_grant=true" \
    --data "config.mandatory_scope=false" \
    --data "config.refresh_token_ttl=1209600" \
    --data "config.token_expiration=7200"

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

Global plugins

A plugin which is not associated to any Service, Route, or Consumer (or API, if you are using an older version of Kong) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Plugins can be configured using the http://kong:8001/plugins/ endpoint.

Parameters

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

Important: When configuring the plugin, at least one of the following OAuth2 auth flows must be enabled:

• Authorization Code
• Client Credentials
• Implicit Grant
• Password Grant

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 all examples in this section.

Enable the plugin with Client Credentials

Command:

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

Result:

{
   "created_at":1589485602,
   "config":{
      "refresh_token_ttl":1209600,
      "auto_approve":false,
      "provision_key":"D7gc8R1vGD5lkod2wUrSRdpBPpte73kF",
      "mandatory_scope":false,
      "scopes":null,
      "enable_implicit_grant":false,
      "display_name":"my_service_display_name",
      "enable_client_credentials":true,
      "description":null,
      "enable_password_grant":false,
      "enable_authorization_code":false,
      "token_expiration":7200,
      "auth_header_name":"authorization"
   },
   "id":"7696f657-00f9-462e-9d63-96d27140d2f8",
   "service":{
      "id":"c2a45fd2-e753-46a0-955d-2ac7b4a18ce0"
   },
   "name":"application-registration",
   "protocols":[
      "grpc",
      "grpcs",
      "http",
      "https"
   ],
   "enabled":true,
   "run_on":null,
   "consumer":null,
   "route":null,
   "tags":null
}

Note that the provision_key was autogenerated.

Enable the plugin with Authorization Code

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

Enable the plugin with Password Grant

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

Enable the plugin with Implicit Grant

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

Set tokens to never expire

Set the config.refresh_token_ttl and config.token_expiration values to 0.

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

Set mandatory scopes

Replace <read> and <write> with the name of your scopes.

curl -X  POST http://<DNSorIP>:8001/services/{service} \
    --data "name=application-registration"  \
    --data "config.display_name=<my_service_display_name>" \
    --data "config.enable_authorization_code=true" \
    --data "config.mandatory_scope=true" \
    --data "config.scopes[]=<read>"

Multiple scopes:

  ...
    --data "config.scopes[]=<read> <write>"

The scopes string array is space delimited.

Enable automatic registration approval

Enable auto_approve so that application registration requests are automatically approved. 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"