basic-auth

The basic-auth plugin adds basic access authentication for consumers to authenticate themselves before being able to access upstream resources.

When a consumer is successfully authenticated, APISIX adds additional headers, such as X-Consumer-Username, X-Credential-Identifier, and other consumer custom headers if configured, to the request, before proxying it to the upstream service. The upstream service will be able to differentiate between consumers and implement additional logics as needed. If any of these values is not available, the corresponding header will not be added.

About X-Consumer-Username

When consumers are configured using the Ingress Controller, the consumer name is generated in the format namespace_consumername. As a result, the X-Consumer-Username header will also follow this format instead of just consumername.

Examples

The examples below demonstrate how you can work with the basic-auth plugin for different scenarios.

Implement Basic Authentication on Route

The following example demonstrates how to implement basic authentication on a route.

Admin API
ADC
Ingress Controller

Create a consumer johndoe:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "johndoe"
  }'

Create basic-auth credential for the consumer:

curl "http://127.0.0.1:9180/apisix/admin/consumers/johndoe/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-basic-auth",
    "plugins": {
      "basic-auth": {
        "username": "johndoe",
        "password": "john-key"
      }
    }
  }'

Create a route with basic-auth:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "basic-auth-route",
    "uri": "/anything",
    "plugins": {
      "basic-auth": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Create a consumer with basic-auth credential and a route with basic-auth plugin configured:

adc.yaml
consumers:
  - username: johndoe
    credentials:
      - name: basic-auth
        type: basic-auth
        config:
          username: johndoe
          password: john-key
services:
  - name: basic-auth-service
    routes:
      - name: basic-auth-route
        uris:
          - /anything
        plugins:
          basic-auth: {}
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

Synchronize the configuration to the gateway:

adc sync -f adc.yaml

Create a consumer with basic-auth credential and a route with basic-auth plugin configured:

Gateway API
APISIX CRD

basic-auth-ic.yaml
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: aic
  name: johndoe
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: basic-auth
      name: primary-cred
      config:
        username: johndoe
        password: john-key
---
apiVersion: v1
kind: Service
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: basic-auth-plugin-config
spec:
  plugins:
    - name: basic-auth
      config:
        _meta:
          disable: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: basic-auth-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: basic-auth-plugin-config
      backendRefs:
        - name: httpbin-external-domain
          port: 80

Apply the configuration to your cluster:

kubectl apply -f basic-auth-ic.yaml

basic-auth-ic.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  namespace: aic
  name: johndoe
spec:
  ingressClassName: apisix
  authParameter:
    basicAuth:
      value:
        username: johndoe
        password: john-key
---
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  ingressClassName: apisix
  externalNodes:
  - type: Domain
    name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: basic-auth-route
spec:
  ingressClassName: apisix
  http:
    - name: basic-auth-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: basic-auth
        enable: true

Apply the configuration to your cluster:

kubectl apply -f basic-auth-ic.yaml

Verify with Valid Credentials

Send a request to the route with valid credentials:

curl -i "http://127.0.0.1:9080/anything" -u johndoe:john-key

You should see an HTTP/1.1 200 OK response similar to the following:

{
  "args": {}, 
  "headers": {
    "Accept": "*/*", 
    "Authorization": "Basic am9obmRvZTpqb2huLWtleQ==",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.6.0", 
    "X-Amzn-Trace-Id": "Root=1-66e5107c-5bb3e24f2de5baf733aec1cc",
    "X-Consumer-Username": "johndoe",
    "X-Credential-Identifier": "cred-john-basic-auth",
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  "origin": "192.168.65.1, 205.198.122.37", 
  "url": "http://127.0.0.1/anything"
}

Verify with Invalid Credentials

Send a request with invalid credentials:

curl -i "http://127.0.0.1:9080/anything" -u johndoe:invalid-password

You should see an HTTP/1.1 401 Unauthorized response with the following:

{"message":"Invalid user authorization"}

Verify without Credentials

Send a request without credentials:

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

You should see an HTTP/1.1 401 Unauthorized response with the following:

{"message":"Missing authorization in request"}

Hide Authentication Information From Upstream

The following example demonstrates how to prevent the client's credentials (the Authorization header) from being sent to the upstream services by configuring hide_credentials. If you are using APISIX, the Authorization header containing the client's credentials is forwarded to the upstream services by default, which might lead to security risks in some circumstances and you should consider updating hide_credentials as shown in this example.

Admin API
ADC
Ingress Controller

Create a consumer johndoe:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "johndoe"
  }'

Create basic-auth credential for the consumer:

curl "http://127.0.0.1:9180/apisix/admin/consumers/johndoe/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-basic-auth",
    "plugins": {
      "basic-auth": {
        "username": "johndoe",
        "password": "john-key"
      }
    }
  }'

Without Hiding Credentials

Create a route with basic-auth and configure hide_credentials to false, which is the default configuration:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "id": "basic-auth-route",
  "uri": "/anything",
  "plugins": {
    "basic-auth": {
      "hide_credentials": false
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

Create a consumer with basic-auth credential and a route with basic-auth plugin configured:

adc.yaml
consumers:
  - username: johndoe
    credentials:
      - name: basic-auth
        type: basic-auth
        config:
          username: johndoe
          password: john-key
services:
  - name: basic-auth-service
    routes:
      - name: basic-auth-route
        uris:
          - /anything
        plugins:
          basic-auth:
            hide_credentials: false
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

Synchronize the configuration to the gateway:

adc sync -f adc.yaml

Create a consumer with basic-auth credential and a route with basic-auth plugin configured:

Gateway API
APISIX CRD

basic-auth-ic.yaml
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: aic
  name: johndoe
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: basic-auth
      name: primary-cred
      config:
        username: johndoe
        password: john-key
---
apiVersion: v1
kind: Service
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: basic-auth-plugin-config
spec:
  plugins:
    - name: basic-auth
      config:
        _meta:
          disable: false
        hide_credentials: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: basic-auth-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: basic-auth-plugin-config
      backendRefs:
        - name: httpbin-external-domain
          port: 80

Apply the configuration to your cluster:

kubectl apply -f basic-auth-ic.yaml

basic-auth-ic.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  namespace: aic
  name: johndoe
spec:
  ingressClassName: apisix
  authParameter:
    basicAuth:
      value:
        username: johndoe
        password: john-key
---
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  ingressClassName: apisix
  externalNodes:
  - type: Domain
    name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: basic-auth-route
spec:
  ingressClassName: apisix
  http:
    - name: basic-auth-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: basic-auth
        enable: true
        config:
          hide_credentials: false

Apply the configuration to your cluster:

kubectl apply -f basic-auth-ic.yaml

Send a request with the valid key:

curl -i "http://127.0.0.1:9080/anything" -u johndoe:john-key

You should see an HTTP/1.1 200 OK response with the following:

{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Authorization": "Basic am9obmRvZTpqb2huLWtleQ==",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.6.0", 
    "X-Amzn-Trace-Id": "Root=1-66cc2195-22bd5f401b13480e63c498c6",
    "X-Consumer-Username": "johndoe",
    "X-Credential-Identifier": "cred-john-basic-auth",
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  "json": null, 
  "method": "GET", 
  "origin": "192.168.65.1, 43.228.226.23", 
  "url": "http://127.0.0.1/anything"
}

Note that the credentials are visible to the upstream service in base64-encoded format.

tip

You can also pass the base64-encoded credentials in the request using the Authorization header as such:

curl -i "http://127.0.0.1:9080/anything" -H "Authorization: Basic am9obmRvZTpqb2huLWtleQ=="

Hide Credentials

Admin API
ADC
Ingress Controller

Update the plugin's hide_credentials to true:

curl "http://127.0.0.1:9180/apisix/admin/routes/basic-auth-route" -X PATCH \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "plugins": {
    "basic-auth": {
      "hide_credentials": true
    }
  }
}'

Update the route configuration:

adc.yaml
# other configs
# ...
services:
  - name: basic-auth-service
    routes:
      - name: basic-auth-route
        uris:
          - /anything
        plugins:
          basic-auth:
            hide_credentials: true
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

Synchronize the configuration to the gateway:

adc sync -f adc.yaml

Gateway API
APISIX CRD

Update the PluginConfig to set hide_credentials to true:

basic-auth-ic.yaml
# other configs
# ---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: basic-auth-plugin-config
spec:
  plugins:
    - name: basic-auth
      config:
        _meta:
          disable: false
        hide_credentials: true

Apply the configuration to your cluster:

kubectl apply -f basic-auth-ic.yaml

Update the ApisixRoute to set hide_credentials to true:

basic-auth-ic.yaml
# other configs
# ---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: basic-auth-route
spec:
  ingressClassName: apisix
  http:
    - name: basic-auth-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: basic-auth
        enable: true
        config:
          hide_credentials: true

Apply the configuration to your cluster:

kubectl apply -f basic-auth-ic.yaml

Send a request with the valid key:

curl -i "http://127.0.0.1:9080/anything" -u johndoe:john-key

You should see an HTTP/1.1 200 OK response with the following:

{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.6.0",
    "X-Amzn-Trace-Id": "Root=1-66cc21a7-4f6ac87946e25f325167d53a",
    "X-Consumer-Username": "johndoe",
    "X-Credential-Identifier": "cred-john-basic-auth",
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  "json": null,
  "method": "GET",
  "origin": "192.168.65.1, 43.228.226.23",
  "url": "http://127.0.0.1/anything"
}

Note that the credentials are no longer visible to the upstream service.

Add Consumer Custom ID to Header

The following example demonstrates how you can attach a consumer custom ID to authenticated request in the Consumer-Custom-Id header, which can be used to implement additional logics as needed.

Admin API
ADC
Ingress Controller

Create a consumer johndoe with a custom ID label:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "johndoe",
    "labels": {
      "custom_id": "495aec6a"
    }
  }'

Create basic-auth credential for the consumer:

curl "http://127.0.0.1:9180/apisix/admin/consumers/johndoe/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-basic-auth",
    "plugins": {
      "basic-auth": {
        "username": "johndoe",
        "password": "john-key"
      }
    }
  }'

Create a route with basic-auth:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "basic-auth-route",
    "uri": "/anything",
    "plugins": {
      "basic-auth": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Create a consumer with basic-auth credential and a route with basic-auth plugin enabled:

adc.yaml
consumers:
  - username: johndoe
    labels:
      custom_id: "495aec6a"
    credentials:
      - name: basic-auth
        type: basic-auth
        config:
          username: johndoe
          password: john-key
services:
  - name: basic-auth-service
    routes:
      - name: basic-auth-route
        uris:
          - /anything
        plugins:
          basic-auth: {}
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

Synchronize the configuration to the gateway:

adc sync -f adc.yaml

Consumer custom labels are currently not supported when configuring resources through the Ingress Controller, and the X-Consumer-Custom-Id header is not included in requests. At the moment, this example cannot be completed with the Ingress Controller.

To verify, send a request to the route with the valid key:

curl -i "http://127.0.0.1:9080/anything" -u johndoe:john-key

You should see an HTTP/1.1 200 OK response similar to the following:

{
  "args": {},
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Authorization": "Basic am9obmRvZTpqb2huLWtleQ==", 
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.6.0",
    "X-Amzn-Trace-Id": "Root=1-66ea8d64-33df89052ae198a706e18c2a", 
    "X-Consumer-Username": "johndoe",
    "X-Credential-Identifier": "cred-john-basic-auth",
    "X-Consumer-Custom-Id": "495aec6a",
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  "json": null, 
  "method": "GET", 
  "origin": "192.168.65.1, 205.198.122.37", 
  "url": "http://127.0.0.1/anything"
}

If you would like to attach more consumer custom headers to authenticated requests, see the attach-consumer-label plugin.

Rate Limit with Anonymous Consumer

The following example demonstrates how you can configure different rate limiting policies by regular and anonymous consumers, where the anonymous consumer does not need to authenticate and has less quota.

Admin API
ADC
Ingress Controller

Create a regular consumer johndoe and configure the limit-count plugin to allow for a quota of 3 within a 30-second window:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "johndoe",
    "plugins": {
      "limit-count": {
        "count": 3,
        "time_window": 30,
        "rejected_code": 429,
        "policy": "local"
      }
    }
  }'

Create the basic-auth credential for the consumer johndoe:

curl "http://127.0.0.1:9180/apisix/admin/consumers/johndoe/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-basic-auth",
    "plugins": {
      "basic-auth": {
        "username": "johndoe",
        "password": "john-key"
      }
    }
  }'

Create an anonymous user anonymous and configure the limit-count plugin to allow for a quota of 1 within a 30-second window:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "anonymous",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "policy": "local"
      }
    }
  }'

Create a route and configure the basic-auth plugin to accept anonymous consumer anonymous from bypassing the authentication:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "basic-auth-route",
    "uri": "/anything",
    "plugins": {
      "basic-auth": {
        "anonymous_consumer": "anonymous"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Configure consumers with different rate limits and a route that accepts anonymous users:

adc.yaml
consumers:
  - username: johndoe
    plugins:
      limit-count:
        count: 3
        time_window: 30
        rejected_code: 429
        policy: local
    credentials:
      - name: basic-auth
        type: basic-auth
        config:
          username: johndoe
          password: john-key
  - username: anonymous
    plugins:
      limit-count:
        count: 1
        time_window: 30
        rejected_code: 429
        policy: local
services:
  - name: anonymous-rate-limit-service
    routes:
      - name: basic-auth-route
        uris:
          - /anything
        plugins:
          basic-auth:
            anonymous_consumer: anonymous
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

Synchronize the configuration to the gateway:

adc sync -f adc.yaml

Gateway API
APISIX CRD

Configure consumers with different rate limits and a route that accepts anonymous users:

basic-auth-ic.yaml
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: aic
  name: johndoe
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: basic-auth
      name: primary-key
      config:
        username: johndoe
        password: john-key
  plugins:
    - name: limit-count
      config:
        count: 3
        time_window: 30
        rejected_code: 429
        policy: local
---
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: aic
  name: anonymous
spec:
  gatewayRef:
    name: apisix
  plugins:
    - name: limit-count
      config:
        count: 1
        time_window: 30
        rejected_code: 429
        policy: local
---
apiVersion: v1
kind: Service
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: basic-auth-plugin-config
spec:
  plugins:
    - name: basic-auth
      config:
        anonymous_consumer: aic_anonymous  # namespace_consumername
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: basic-auth-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: basic-auth-plugin-config
      backendRefs:
        - name: httpbin-external-domain
          port: 80

Apply the configuration to your cluster:

kubectl apply -f basic-auth-ic.yaml

note

The ApisixConsumer CRD currently does not support configuring plugins on consumers, except for the authentication plugins allowed in authParameter. This example cannot be completed with APISIX CRDs.

To verify, send five consecutive requests with johndoe's credentials:

resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/anything" -u johndoe:john-key -o /dev/null -s -w "%{http_code}\n") && \
  count_200=$(echo "$resp" | grep "200" | wc -l) && \
  count_429=$(echo "$resp" | grep "429" | wc -l) && \
  echo "200": $count_200, "429": $count_429

You should see the following response, showing that out of the 5 requests, 3 requests were successful (status code 200) while the others were rejected (status code 429).

200:    3, 429:    2

Send five anonymous requests:

resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/anything" -o /dev/null -s -w "%{http_code}\n") && \
  count_200=$(echo "$resp" | grep "200" | wc -l) && \
  count_429=$(echo "$resp" | grep "429" | wc -l) && \
  echo "200": $count_200, "429": $count_429

You should see the following response, showing that only one request was successful:

200:    1, 429:    4

Examples​

Implement Basic Authentication on Route​

Verify with Valid Credentials​

Verify with Invalid Credentials​

Verify without Credentials​

Hide Authentication Information From Upstream​

Without Hiding Credentials​

Hide Credentials​

Add Consumer Custom ID to Header​

Rate Limit with Anonymous Consumer​

Examples

Implement Basic Authentication on Route

Verify with Valid Credentials

Verify with Invalid Credentials

Verify without Credentials

Hide Authentication Information From Upstream

Without Hiding Credentials

Hide Credentials

Add Consumer Custom ID to Header

Rate Limit with Anonymous Consumer