public-api

Description

The public-api plugin is used to enhance the plugin public API access control. When current users develop custom plugins, they can register some public APIs for fixed functionality, such as the /apisix/plugin/jwt/sign API in jwt-auth. These APIs can only apply limited plugins for access control (currently only ip-restriction) by way of plugin interceptors.

With the public-api plugin, we put all public APIs into the general HTTP API router, which is consistent with the normal Route registered by the user and can apply any plugin. The public API added in the user plugin is no longer expose by default by APISIX, and the user has to manually configure the Route for it, the user can configure any uri and plugin.

Attributes

NameTypeRequirementDefaultValidDescription
uristringoptional“”The uri of the public API. When you set up the route, you can use this to configure the original API uri if it is used in a way that is inconsistent with the original public API uri.

Example

We take the jwt-auth token sign API as an example to show how to configure the public-api plugin. Also, the key-auth will be used to show how to configure the protection plugin for the public API.

Prerequisites

The use of key-auth and jwt-auth requires the configuration of a consumer that contains the configuration of these plugins, and you need to create one in advance, the process will be omitted here.

Basic Use Case

First we will setup a route.

  1. $ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r1' \
  2.     -H 'X-API-KEY: <api-key>' \
  3.     -H 'Content-Type: application/json' \
  4.     -d '{
  5.     "uri": "/apisix/plugin/jwt/sign",
  6.     "plugins": {
  7.         "public-api": {}
  8.     }
  9. }'

Let’s test it.

  1. $ curl 'http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key'

It will respond to a text JWT.

Customize URI

Let’s setup another route.

  1. $ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r2' \
  2.     -H 'X-API-KEY: <api-key>' \
  3.     -H 'Content-Type: application/json' \
  4.     -d '{
  5.     "uri": "/gen_token",
  6.     "plugins": {
  7.         "public-api": {
  8.             "uri": "/apisix/plugin/jwt/sign"
  9.         }
  10.     }
  11. }'

Let’s test it.

  1. $ curl 'http://127.0.0.1:9080/gen_token?key=user-key'

It will still respond to a text JWT. We can see that users are free to configure URI for the public API to match.

Protect Route

Let’s modify the last route and add key-auth authentication to it.

  1. $ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r2' \
  2.     -H 'X-API-KEY: <api-key>' \
  3.     -H 'Content-Type: application/json' \
  4.     -d '{
  5.     "uri": "/gen_token",
  6.     "plugins": {
  7.         "public-api": {
  8.             "uri": "/apisix/plugin/jwt/sign"
  9.         },
  10.         "key-auth": {}
  11.     }
  12. }'

Let’s test it.

  1. $ curl -i 'http://127.0.0.1:9080/gen_token?key=user-key'
  2.     -H "apikey: test-apikey"
  3. HTTP/1.1 200 OK
  6. # Failed request
  7. $ curl -i 'http://127.0.0.1:9080/gen_token?key=user-key'
  8. HTTP/1.1 401 UNAUTHORIZED

It will still respond to a text JWT. If we don’t add apikey to the request header, it will respond with a 401 block request. In this way, we have implemented a plugin approach to protect the public API.