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 AuthenticationFor 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:
namespace: ingress-apisix
name: apisix
spec:
controllerName: apisix.apache.org/apisix-ingress-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
namespace: ingress-apisix
name: apisix
spec:
gatewayClassName: apisix
listeners:
- name: http
protocol: HTTP
port: 80
infrastructure:
parametersRef:
group: apisix.apache.org
kind: GatewayProxy
name: apisix-config
Note that the port
in the Gateway listener is required but ignored. This is due to limitations in the data plane: it cannot dynamically open new ports. Since the Ingress Controller does not manage the data plane deployment, it cannot automatically update the configuration or restart the data plane to apply port changes.
If you are using Ingress or APISIX custom resources, you can proceed without additional configuration, as the IngressClass resource below is already applied with installation:
Show configuration
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: apisix
spec:
controller: apisix.apache.org/apisix-ingress-controller
parameters:
apiGroup: apisix.apache.org
kind: GatewayProxy
name: apisix-config
namespace: ingress-apisix
scope: Namespace
See Define Controller and Gateway for more information on parameters.
- Gateway API
- APISIX CRD
Create a Kubernetes manifest file to configure a consumer:
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
namespace: ingress-apisix
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:
apiVersion: v1
kind: Service
metadata:
namespace: ingress-apisix
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: ingress-apisix
name: auth-plugin-config
spec:
plugins:
- name: key-auth
config:
_meta:
disable: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: ingress-apisix
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:
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
namespace: ingress-apisix
name: tom
spec:
ingressClassName: apisix
authParameter:
keyAuth:
value:
key: secret-key
Create a Kubernetes manifest file to configure a route and enable key authentication:
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: ingress-apisix
name: httpbin-external-domain
spec:
externalNodes:
- type: Domain
name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: ingress-apisix
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
#
VerifyExpose 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.