Version: Next

Key Authentication

APISIX has a flexible plugin extension system and a number of existing plugins for user authentication and authorization.

In this tutorial, you will create a Consumer, configure its key authentication Credential, and enable key authentication on a route, using APISIX Ingress Controller.

Prerequisite#

Complete Get APISIX and APISIX Ingress Controller.

Configure Key Authentication#

For demonstration purpose, you will be creating a route to the publicly hosted httpbin services. If you would like to proxy requests to services on Kubernetes, please modify accordingly.

important

If you are using Gateway API, you should first configure the GatewayClass and Gateway resources:

Show configuration

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: apisix
spec:
  controllerName: apisix.apache.org/apisix-ingress-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: apisix
spec:
  gatewayClassName: apisix
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  infrastructure:
    parametersRef:
      group: apisix.apache.org
      kind: GatewayProxy
      name: apisix-config

If you are using Ingress or APISIX custom resources, you can proceed without additional configuration.

Gateway API
APISIX CRD

Create a Kubernetes manifest file to configure a consumer:

consumer.yaml

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  name: tom
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: primary-key
      config:
        key: secret-key

Create a Kubernetes manifest file to configure a route and enable key authentication:

httpbin-route.yaml

apiVersion: v1
kind: Service
metadata:
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  name: auth-plugin-config
spec:
  plugins:
    - name: key-auth
      config:
        _meta:
          disable: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: getting-started-ip
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches: 
    - path:
        type: Exact
        value: /ip
    filters:
    - type: ExtensionRef
      extensionRef:
        group: apisix.apache.org
        kind: PluginConfig
        name: auth-plugin-config
    backendRefs:
    - name: httpbin-external-domain
      port: 80

Apply the configurations to your cluster:

kubectl apply -f consumer.yaml -f httpbin-route.yaml

Create a Kubernetes manifest file to configure a consumer:

consumer.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  name: tom
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      value:
        key: secret-key

Create a Kubernetes manifest file to configure a route and enable key authentication:

httpbin-route.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  name: httpbin-external-domain
spec:
  externalNodes:
  - type: Domain
    name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  name: getting-started-ip
spec:
  ingressClassName: apisix
  http:
    - name: getting-started-ip
      match:
        paths:
          - /ip
      upstreams:
      - name: httpbin-external-domain
      authentication:
        enable: true
        type: keyAuth

Apply the configurations to your cluster:

kubectl apply -f consumer.yaml -f httpbin-route.yaml

Verify#

Expose the service port to your local machine by port forwarding:

kubectl port-forward svc/apisix-gateway 9080:80 &

Send a request without the apikey header.

curl -i "http://127.0.0.1:9080/ip"

You should receive an an HTTP/1.1 401 Unauthorized response.

Send a request with a wrong key in the apikey header.

curl -i "http://127.0.0.1:9080/ip" -H 'apikey: wrong-key'

Since the key is incorrect, you should receive an HTTP/1.1 401 Unauthorized response.

Send a request with the correct key in the apikey header.

curl -i "http://127.0.0.1:9080/ip" -H 'apikey: secret-key'

You should receive an HTTP/1.1 200 OK response.