Support multiple authentication methods

Related Documentation
Related Resources
TL;DR

Create an anonymous consumer that will be used when validation fails. Attach a request-termination plugin to this consumer to ensure that traffic is blocked if the request does not match another consumer’s credentials.

Prerequisites

If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

  1. The following Konnect items are required to complete this tutorial:
    • Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
  2. Set the personal access token as an environment variable:

    export KONNECT_TOKEN='YOUR KONNECT TOKEN'
    
    Copied to clipboard!

Allowing multiple authentication methods

The default behavior for Kong Gateway authentication plugins is to require credentials for all requests even if a request has been authenticated through another plugin. Configure an anonymous Consumer on your authentication plugins to set authentication options.

Create Consumers

Create two Consumers that use different authentication methods:

  • consumer-1 uses basic-auth
  • consumer-2 uses key-auth
  1. Create a secret to add a basic-auth credential for consumer-1:

     echo '
     apiVersion: v1
     kind: Secret
     metadata:
       name: consumer-1-basic-auth
       namespace: kong
       labels:
         konghq.com/credential: basic-auth
     stringData:
         username: consumer-1
         password: consumer-1-password
     ' | kubectl apply -f -
    
    Copied to clipboard!
  2. Create a secret to add a key-auth credential for consumer-2:

     echo '
     apiVersion: v1
     kind: Secret
     metadata:
       name: consumer-2-key-auth
       namespace: kong
       labels:
         konghq.com/credential: key-auth
     stringData:
       key: consumer-2-password
     ' | kubectl apply -f -
    
    Copied to clipboard!
  3. Create a Consumer named consumer-1:

    echo "
    apiVersion: configuration.konghq.com/v1
    kind: KongConsumer
    metadata:
      name: consumer-1
      namespace: kong
      annotations:
        kubernetes.io/ingress.class: kong
    username: consumer-1
    credentials:
    - consumer-1-basic-auth
    " | kubectl apply -f -
    
    Copied to clipboard!
  4. Create a Consumer named consumer-2:

    echo "
    apiVersion: configuration.konghq.com/v1
    kind: KongConsumer
    metadata:
      name: consumer-2
      namespace: kong
      annotations:
        kubernetes.io/ingress.class: kong
    username: consumer-2
    credentials:
    - consumer-2-key-auth
    " | kubectl apply -f -
    
    Copied to clipboard!

Secure the service

Once the Consumers and credentials are created, you can add authentication plugins to your Service.

First, create a key-auth plugin. Notice the anonymous configuration option, which means that if no credentials match, the consumer named anonymous is assigned to the request:

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

As Consumer 2 is using basic-auth, we also need to create a basic-auth plugin:

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: basic-auth
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
config:
  anonymous: anonymous
plugin: basic-auth
" | kubectl apply -f -
Copied to clipboard!

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

kubectl annotate -n kong service echo konghq.com/plugins=key-auth,basic-auth --overwrite
Copied to clipboard!

Create an anonymous Consumer

Your endpoints are now secure, but neither Consumer can access the endpoint when providing valid credentials. This is because each plugin will verify the Consumer using it’s own authentication method.

To allow multiple authentication methods, create an anonymous Consumer which is the default user if no valid credentials are provided:

echo "
apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: anonymous
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
username: anonymous
" | kubectl apply -f -
Copied to clipboard!

All requests to the API will now succeed as the anonymous Consumer is being used as a default.

To secure the API once again, add a request termination plugin to the anonymous Consumer that returns HTTP 401:

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: request-termination
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
config:
  message: Authentication required
  status_code: 401
plugin: request-termination
" | kubectl apply -f -
Copied to clipboard!

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

kubectl annotate -n kong  anonymous konghq.com/plugins=request-termination
Copied to clipboard!

Create an HTTPRoute

To route HTTP traffic, you need to create an HTTPRoute or an Ingress resource pointing at your Kubernetes Service.

Validate your configuration

Once the resource has been reconciled, you’ll be able to call the /echo endpoint and Kong Gateway will route the request to the echo service.

Let’s check that authentication works.

Try to access the Gateway Service via the /anything Route using a nonsense API key:

curl "$PROXY_IP/echo" \
     -H "apikey:nonsense"
Copied to clipboard!

The request should now fail with a 401 response and your configured error message, as this Consumer is considered anonymous.

You should get the same result if you try to access the Route without any API key:

curl "$PROXY_IP/echo"
Copied to clipboard!

Finally, try accessing the Route with the configured basic auth credentials:

curl "$PROXY_IP/echo" \
     -u consumer-1:consumer-1-password
Copied to clipboard!

This time, authentication should succeed with a 200.

Cleanup

kubectl delete -n kong -f https://developer.konghq.com/manifests/kic/echo-service.yaml
Copied to clipboard!

Did this doc help?

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!