Key Authentication

TL;DR

Create a KongPlugin resource containing an authentication plugin configuration and annotate your Kubernetes service with the plugin name

kubectl annotate service YOUR_SERVICE konghq.com/plugins=key-auth

Prerequisites

This page is part of the Getting Started with KIC series.

Complete the previous page, Proxy Caching before completing this page.

Understanding authentication

Authentication is the process of verifying that a requester has permissions to access a resource. An API gateway can authenticate the flow of data to and from your upstream services.

Kong Gateway has a library of plugins that support the most widely used methods of API gateway authentication.

Common authentication methods include:

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

Authentication benefits

With Kong Gateway controlling authentication, requests won’t reach upstream services unless the client has successfully authenticated. This means upstream services process pre-authorized requests, freeing them from the cost of authentication, which is a savings in compute time and development effort.

Kong Gateway has visibility into all authentication attempts and enables you to build monitoring and alerting capabilities which support service availability and compliance.

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

Add authentication to the echo service

  1. Create a new key-auth plugin.

     echo "
     apiVersion: configuration.konghq.com/v1
     kind: KongPlugin
     metadata:
       name: key-auth
       namespace: kong
       annotations:
         kubernetes.io/ingress.class: kong
     plugin: key-auth
     " | kubectl apply -f -
    

    Next, apply the KongPlugin resource by annotating the service resource:

     kubectl annotate -n kong service echo konghq.com/plugins=rate-limit-5-min,key-auth --overwrite
    
  2. Test that the API is secure by sending a request using curl -i $PROXY_IP/echo:

     curl -i $PROXY_IP/echo 
    
     curl -i $PROXY_IP/echo 
    

    This request returns a 401 error with the message Unauthorized.

    You should see the response:

     HTTP/1.1 401 Unauthorized
     Date: Wed, 11 Jan 2044 18:33:46 GMT
     Content-Type: application/json; charset=utf-8
     WWW-Authenticate: Key realm="kong"
     Content-Length: 45
     X-Kong-Response-Latency: 1
     Server: kong/3.9.1
    
     {
       "message":"No API key found in request"
     }
    

Set up Consumers and keys

Key authentication in Kong Gateway works by using the Consumer entity. Keys are assigned to Consumers, and client applications present the key within the requests they make.

Keys are stored as Kubernetes Secrets and Consumers are managed with the KongConsumer CRD.

  1. Create a new Secret labeled to use key-auth credential type:

     echo '
     apiVersion: v1
     kind: Secret
     metadata:
        name: alex-key-auth
        namespace: kong
        labels:
           konghq.com/credential: key-auth
     stringData:
        key: hello_world
     ' | kubectl apply -f -
    
  2. Create a new Consumer and attach the credential:

     echo "
     apiVersion: configuration.konghq.com/v1
     kind: KongConsumer
     metadata:
       name: alex
       namespace: kong
       annotations:
         kubernetes.io/ingress.class: kong
     username: alex
     credentials:
     - alex-key-auth
     " | kubectl apply -f -
    
  3. Make a request to the API and provide your apikey:

     curl "$PROXY_IP/echo" \
          -H "apikey:hello_world"
    
     curl "$PROXY_IP/echo" \
          -H "apikey:hello_world"
    

    The results should look like this:

     Welcome, you are connected to node orbstack.
     Running on Pod echo-965f7cf84-mvf6g.
     In namespace default.
     With IP address 192.168.194.10.
    

Next Steps

Congratulations! By making it this far you’ve deployed Kong Ingress Controller, configured a Service and Route, added rate limiting, proxy caching, and API authentication, all using your normal Kubernetes workflow.

You can learn more about the available plugins (including Kubernetes configuration instructions) on the Plugin Hub. For more information about Kong Ingress Controller and how it works, see the how Kong Ingress Controller works section.

Something wrong?

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!