Secure your Services Using Authentication

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

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

    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

    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. http :8001/routes/mocking/plugins \
    2.   name=key-auth

    Try to access the service again:

    cURL

    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.    config:
      16.      minute: 5
      17.      policy: local
      18.  - name: proxy-cache
      19.    config:
      20.      content_type:
      21.      - "application/json; charset=utf-8"
      22.      cache_ttl: 30

    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. 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.    port: 80
      5.    protocol: http
      6.    routes:
      7.    - name: mocking
      8.      paths:
      9.      - /mock
      11.      plugins:
      12.      - name: key-auth
      13.  consumers:
      14.  - custom_id: consumer
      15.    username: consumer
      16.    keyauth_credentials:
      17.    - key: apikey
      18.  plugins:
      19.  - name: rate-limiting
      20.    config:
      21.      minute: 5
      22.      policy: local
      23.  - name: proxy-cache
      24.    config:
      25.      content_type:
      26.      - "application/json; charset=utf-8"
      27.      cache_ttl: 30
      28.      strategy: memory
      1.  deck sync

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

    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:

    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:

    2. Sync the configuration:

      1.  $ deck sync

    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 route with authentication.