Secure your Services Using Authentication

In this topic, you’ll learn about API Gateway authentication, set up the Key Authentication plugin, and add a consumer.

If you are following the getting started workflow, make sure you have completed Improve Performance with Proxy Caching before moving on.

What is Authentication?

API gateway authentication is an important way to control the data that is allowed to be transmitted using your APIs. Basically, it checks that a particular consumer has permission to access the API, using a predefined set of credentials.

Kong Gateway has a library of plugins that provide simple ways to implement the best known and most widely used methods of API gateway authentication. Here are some of the commonly used ones:

  • Basic Authentication
  • Key Authentication
  • OAuth 2.0 Authentication
  • LDAP Authentication Advanced
  • OpenID Connect

Authentication plugins can be configured to apply to service entities within the Kong Gateway. In turn, service entities are mapped one-to-one with the upstream services they represent, essentially meaning that the authentication plugins apply directly to those upstream services.

Why use API Gateway Authentication?

With authentication turned on, Kong Gateway won’t proxy requests unless the client successfully authenticates first. This means that the upstream (API) doesn’t need to authenticate client requests, and it doesn’t waste critical resources validating credentials.

Kong Gateway has visibility into all authentication attempts, successful, failed, and so on, which provides the ability to catalog and dashboard those events to prove the right controls are in place, and to achieve compliance. Authentication also gives you an opportunity to determine how a failed request is handled. This might mean simply blocking the request and returning an error code, or in some circumstances, you might still want to provide limited access.

In this example, you’re going to enable the Key Authentication plugin. API key authentication is one of the most popular ways to conduct API authentication and can be implemented to create and delete access keys as required.

For more information, see What is API Gateway Authentication?.

Set up the Key Authentication Plugin

Using Kong Manager

Using the Admin API

Using decK (YAML)

  1. Access your Kong Manager instance and your default workspace.
  2. Go to the Routes page and select the mocking route you created.
  3. Click View.
  4. On the Scroll down and select the Plugins tab, then click Add a Plugin.
  5. In the Authentication section, find the Key Authentication plugin and click Enable.

  6. In the Create new key-auth plugin dialog, the plugin fields are automatically scoped to the route because the plugin is selected from the mocking Routes page.

    For this example, this means that you can use all of the default values.

  7. Click Create.

    Once the plugin is enabled on the route, key-auth displays under the Plugins section on the route’s overview page.

Now, if you try to access the route without providing an API key, the request will fail, and you’ll see the message "No API key found in request".

Before Kong proxies requests for this route, it needs an API key. For this example, since you installed the Key Authentication plugin, you need to create a consumer with an associated key first.

Call the Admin API on port 8001 and configure plugins to enable key authentication. For this example, apply the plugin to the /mock route you created:

cURL

HTTPie

  1. curl -X POST http://<admin-hostname>:8001/routes/mocking/plugins \
  2.   --data name=key-auth
  1. http :8001/routes/mocking/plugins \
  2.   name=key-auth

Try to access the service again:

cURL

HTTPie

  1. curl -i http://<admin-hostname>:8000/mock
  1. http :8000/mock

Since you added key authentication, you should be unable to access it:

  1. HTTP/1.1 401 Unauthorized
  2. ...
  3. {
  4.     "message": "No API key found in request"
  5. }

Before Kong proxies requests for this route, it needs an API key. For this example, since you installed the Key Authentication plugin, you need to create a consumer with an associated key first.

  1. Under the mocking route in the routes section of the kong.yaml file, add a plugin section and enable the key-auth plugin:

    1.  plugins:
    2.  - name: key-auth

    Your file should now look like this:

    1.  _format_version: "1.1"
    2.  services:
    3.  - host: mockbin.org
    4.    name: example_service
    5.    port: 80
    6.    protocol: http
    7.    routes:
    8.    - name: mocking
    9.      paths:
    10.      - /mock
    11.      strip_path: true
    12.      plugins:
    13.      - name: key-auth
    14.  plugins:
    15.  - name: rate-limiting
    16.    config:
    17.      minute: 5
    18.      policy: local
    19.  - name: proxy-cache
    20.    config:
    21.      content_type:
    22.      - "application/json; charset=utf-8"
    23.      cache_ttl: 30
    24.      strategy: memory

  2. Sync the configuration:

    1.  deck sync

Now, if you try to access the route at http://<admin-hostname>:8000/mock without providing an API key, the request will fail, and you’ll see the message "No API key found in request".

Before Kong proxies requests for this route, it needs an API key. For this example, since you installed the Key Authentication plugin, you need to create a consumer with an associated key first.

Set up Consumers and Credentials

Using Kong Manager

Using the Admin API

Using decK (YAML)

  1. In Kong Manager, go to API Gateway > Consumers.
  2. Click New Consumer.
  3. Enter the Username and Custom ID. For this example, use consumer for each field.
  4. Click Create.
  5. On the Consumers page, find your new consumer and click View.
  6. Scroll down the page and click the Credentials tab.
  7. Click New Key Auth Credential.
  8. Set the key to apikey and click Create.

The new Key Authentication ID displays on the Consumers page under the Credentials tab.

To create a consumer, call the Admin API and the consumer’s endpoint. The following creates a new consumer called consumer:

cURL

HTTPie

  1. curl -i -X POST http://<admin-hostname>:8001/consumers/ \
  2.   --data username=consumer \
  3.   --data custom_id=consumer
  1. http :8001/consumers \
  2.   username=consumer \
  3.   custom_id=consumer

Once provisioned, call the Admin API to provision a key for the consumer created above. For this example, set the key to apikey.

cURL

HTTPie

  1. curl -i -X POST http://<admin-hostname>:8001/consumers/consumer/key-auth \
  2.   --data key=apikey
  1. http :8001/consumers/consumer/key-auth \
  2.   key=apikey

If no key is entered, Kong automatically generates the key.

Result:

  1. HTTP/1.1 201 Created
  2. ...
  3. {
  4.     "consumer": {
  5.         "id": "2c43c08b-ba6d-444a-8687-3394bb215350"
  6.     },
  7.     "created_at": 1568255693,
  8.     "id": "86d283dd-27ee-473c-9a1d-a567c6a76d8e",
  9.     "key": "apikey"
  10. }

You now have a consumer with an API key provisioned to access the route.

  1. Add a consumers section to your kong.yaml file and create a new consumer:

    1.  consumers:
    2.  - custom_id: consumer
    3.    username: consumer
    4.    keyauth_credentials:
    5.    - key: apikey

    Your file should now look like this:

    1.  _format_version: "1.1"
    2.  services:
    3.  - host: mockbin.org
    4.    name: example_service
    5.    port: 80
    6.    protocol: http
    7.    routes:
    8.    - name: mocking
    9.      paths:
    10.      - /mock
    11.      strip_path: true
    12.      plugins:
    13.      - name: key-auth
    14.  consumers:
    15.  - custom_id: consumer
    16.    username: consumer
    17.    keyauth_credentials:
    18.    - key: apikey
    19.  plugins:
    20.  - name: rate-limiting
    21.    config:
    22.      minute: 5
    23.      policy: local
    24.  - name: proxy-cache
    25.    config:
    26.      content_type:
    27.      - "application/json; charset=utf-8"
    28.      cache_ttl: 30
    29.      strategy: memory

  2. Sync the configuration:

    1.  deck sync

You now have a consumer with an API key provisioned to access the route.

Validate Key Authentication

Using a Web Browser

Using the Admin API

To validate the Key Authentication plugin, access your route through your browser by appending ?apikey=apikey to the url:

  1. http://<admin-hostname>:8000/mock?apikey=apikey

To validate the Key Authentication plugin, access the mocking route again, using the header apikey with a key value of apikey.

cURL

HTTPie

  1. curl -i http://<admin-hostname>:8000/mock/request \
  2.   -H 'apikey:apikey'
  1. http :8000/mock/request apikey:apikey

You should get an HTTP/1.1 200 OK message in response.

(Optional) Disable the plugin

If you are following this getting started guide topic by topic, you will need to use this API key in any requests going forward. If you don’t want to keep specifying the key, disable the plugin before moving on.

Using Kong Manager

Using the Admin API

Using decK (YAML)

  1. Go to the Plugins page and click on View for the key-auth row.
  2. Use the toggle at the top of the page to switch the plugin from Enabled to Disabled.

Find the plugin ID and copy it:

cURL

HTTPie

  1. curl -X GET http://<admin-hostname>:8001/routes/mocking/plugins/
  1. http :8001/routes/mocking/plugins

Output:

  1. "id": "2512e48d9-7by0-674c-84b7-00606792f96b"

Disable the plugin:

cURL

HTTPie

  1. curl -X PATCH http://<admin-hostname>:8001/routes/mocking/plugins/{<plugin-id>} \
  2.   --data enabled=false
  1. http -f patch :8001/routes/mocking/plugins/{<plugin-id>} \
  2.   enabled=false

  1. Disable the key-auth plugin in the kong.yaml file by setting enabled to false:

    1.  plugins:
    2.  - name: key-auth
    3.    enabled: false

  2. Sync the configuration:

    1.  $ deck sync

Summary and next steps

In this topic, you:

  • Enabled the Key Authentication plugin.
  • Created a new consumer named consumer.
  • Gave the consumer an API key of apikey so that it could access the /mock route with authentication.

Next, you’ll learn about load balancing upstream services using targets.