Configure Basic Authentication

Require a username and password on an API7 Gateway route and verify the resolved consumer identity.

Goal

A route that rejects requests without Basic credentials and forwards valid requests with the caller identified as a named consumer.

The basic-auth (opens in Plugin Hub docs) plugin validates the standard HTTP Authorization header against consumer credentials. This example sets hide_credentials: true so the header is removed before proxying.

Before you begin

Set the variables before running any checks:

export API7_ADMIN_URL="https://localhost:7443"
export API7_GATEWAY_GROUP_ID="default"   # only the group the quickstart creates; otherwise copy the gateway group's UUID from Gateway Groups in the Dashboard
read -rp "Gateway group name for ADC (if used): " API7_GATEWAY_GROUP_NAME && export API7_GATEWAY_GROUP_NAME
export GATEWAY_URL="http://127.0.0.1:9080"
read -rsp "Dashboard token: " API7_ADMIN_KEY && export API7_ADMIN_KEY && echo

An API7 Gateway control plane is reachable and your Dashboard token is valid:

curl -ks -o /dev/null -w '%{http_code}\n' "${API7_ADMIN_URL}/api/gateway_groups" \
  -H "X-API-KEY: ${API7_ADMIN_KEY}"

Expected: 200.

A gateway instance in the selected group reports Healthy:

curl -ks "${API7_ADMIN_URL}/api/gateway_groups/${API7_GATEWAY_GROUP_ID}/instances" \
  -H "X-API-KEY: ${API7_ADMIN_KEY}" | grep -o '"status": *"Healthy"' | wc -l

Expected: 1 or more.

Required local tools are available:
```
jq --version
```
Expected: a jq version.
For the ADC path, ADC is installed and supports label selectors:
```
adc --version
adc sync --help | grep -- '--label-selector'
```
Expected: a version string and a help entry for --label-selector. The option is documented in ADC v0.30.3; use a version whose help lists it. ADC looks up --gateway-group by gateway group display name, so API7_GATEWAY_GROUP_NAME is distinct from the UUID used by the compatibility Admin API. Enter the name of the same group identified by API7_GATEWAY_GROUP_ID. If similar group names make the lookup ambiguous, stop and confirm which group your installed ADC resolves before continuing.

ADC writes diff.yaml in the current directory. Before saving or running this guide's ADC examples, confirm that none of its local paths already exists:
```
for file in basic-auth-adc.yaml basic-auth-cleanup.yaml diff.yaml; do test ! -e "${file}" || { echo "Stop: ${file} already exists"; exit 1; }; done
```
Expected: no output. This makes the local cleanup safe; otherwise use a new empty working directory.

This guide creates only these gateway resources: basic-auth-httpbin-service, basic-auth-route, basic-auth-consumer, and basic-auth-consumer-cred. Check that the first three names are unused:

curl -ks -w '\nHTTP status: %{http_code}\n' "${API7_ADMIN_URL}/apisix/admin/services/basic-auth-httpbin-service?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -H "X-API-KEY: ${API7_ADMIN_KEY}"
curl -ks -w '\nHTTP status: %{http_code}\n' "${API7_ADMIN_URL}/apisix/admin/routes/basic-auth-route?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -H "X-API-KEY: ${API7_ADMIN_KEY}"
curl -ks -w '\nHTTP status: %{http_code}\n' "${API7_ADMIN_URL}/apisix/admin/consumers/basic-auth-consumer?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -H "X-API-KEY: ${API7_ADMIN_KEY}"

For the Admin API path, expected: each response reports that the requested resource is absent. If a response has HTTP status 200 and a populated matching value.id or value.username, that ID is already in use; stop or change every occurrence before continuing. Do not treat another error as proof of absence: correct the token, gateway group, or request until the result is unambiguous. The PUT operations below update a matching ID.

ADC can encounter an object with the same name under a different backend ID, so this check alone does not prove ADC ownership. On the ADC path, continue only if adc diff shows creates for exactly the four example objects and no update, replacement, or deletion of an existing object.

Steps

Choose either the Admin API path in steps 1–3 or the ADC path in step 4. Do not apply both.

Step 1: Create a service with an upstream

curl -ks "${API7_ADMIN_URL}/apisix/admin/services/basic-auth-httpbin-service?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
  -H "X-API-KEY: ${API7_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "basic-auth-httpbin-service",
    "labels": {"guide": "basic-auth"},
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [{"host": "httpbin.org", "port": 80, "weight": 100}]
    }
  }'

{ "value": { "id": "basic-auth-httpbin-service", "name": "basic-auth-httpbin-service", … } }

What changed: the example service now sends traffic to httpbin.org; no route points to it yet.

Step 2: Create a route and enable `basic-auth`

curl -ks "${API7_ADMIN_URL}/apisix/admin/routes/basic-auth-route?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
  -H "X-API-KEY: ${API7_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "basic-auth-route",
    "labels": {"guide": "basic-auth"},
    "paths": ["/anything/basic-auth"],
    "methods": ["GET"],
    "service_id": "basic-auth-httpbin-service",
    "plugins": {"basic-auth": {"hide_credentials": true}}
  }'

{ "value": { "id": "basic-auth-route", "name": "basic-auth-route", … } }

What changed: /anything/basic-auth now requires a valid basic-auth credential. With no credential yet, every request is rejected.

Step 3: Create a consumer and credential

curl -ks "${API7_ADMIN_URL}/apisix/admin/consumers/basic-auth-consumer?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
  -H "X-API-KEY: ${API7_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"username": "basic-auth-consumer", "labels": {"guide": "basic-auth"}}'

curl -ks "${API7_ADMIN_URL}/apisix/admin/consumers/basic-auth-consumer/credentials/basic-auth-consumer-cred?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
  -H "X-API-KEY: ${API7_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "basic-auth-consumer-cred",
    "plugins": {"basic-auth": {"username": "alice", "password": "secret-password"}}
  }'

{ "value": { "username": "basic-auth-consumer", … } }
{ "value": { "id": "basic-auth-consumer-cred", "name": "basic-auth-consumer-cred", … } }

What changed: alice:secret-password resolves to basic-auth-consumer.

Step 4: Apply the same configuration with ADC

Skip this alternative if you completed steps 1–3. Save the complete desired state:

basic-auth-adc.yaml

services:
  - name: basic-auth-httpbin-service
    labels:
      guide: basic-auth
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: basic-auth-route
        labels:
          guide: basic-auth
        uris:
          - /anything/basic-auth
        methods:
          - GET
        plugins:
          basic-auth:
            hide_credentials: true
consumers:
  - username: basic-auth-consumer
    labels:
      guide: basic-auth
    credentials:
      - name: basic-auth-consumer-cred
        type: basic-auth
        config:
          username: alice
          password: secret-password

Lint locally, ask the backend to validate the file, and inspect the diff:

adc lint -f basic-auth-adc.yaml
adc validate -f basic-auth-adc.yaml --backend api7ee --server "${API7_ADMIN_URL}" --token "${API7_ADMIN_KEY}" --gateway-group "${API7_GATEWAY_GROUP_NAME}" --tls-skip-verify --label-selector guide=basic-auth
adc diff -f basic-auth-adc.yaml --backend api7ee --server "${API7_ADMIN_URL}" --token "${API7_ADMIN_KEY}" --gateway-group "${API7_GATEWAY_GROUP_NAME}" --tls-skip-verify --label-selector guide=basic-auth

Expected: lint and validation succeed, and the diff contains only this example's service, nested route, consumer, and credential. The selector scopes reconciliation to top-level resources labeled guide=basic-auth; the route remains part of its selected service.

After reviewing the diff, apply it:

adc sync -f basic-auth-adc.yaml --backend api7ee --server "${API7_ADMIN_URL}" --token "${API7_ADMIN_KEY}" --gateway-group "${API7_GATEWAY_GROUP_NAME}" --tls-skip-verify --label-selector guide=basic-auth

Expected: ADC applies only the changes shown for the guide=basic-auth partition.

What changed: ADC reconciled the reviewed desired state within the guide=basic-auth partition.

Validate

Send a request without credentials:

curl -is "${GATEWAY_URL}/anything/basic-auth" | head -1
curl -s "${GATEWAY_URL}/anything/basic-auth"

HTTP/1.1 401 Unauthorized

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

Send valid credentials and inspect the fields that prove consumer resolution and credential removal:

curl -s "${GATEWAY_URL}/anything/basic-auth" -u alice:secret-password | jq '{headers: {"X-Consumer-Username": .headers["X-Consumer-Username"], "X-Credential-Identifier": .headers["X-Credential-Identifier"]}, authorization_forwarded: (.headers.Authorization != null)}'

{
  "headers": {
    "X-Consumer-Username": "basic-auth-consumer",
    "X-Credential-Identifier": "basic-auth-consumer-cred"
  },
  "authorization_forwarded": false
}

Roll back / Clean up

Use the cleanup path that matches how you created the resources. Both paths are limited to this guide's IDs or label partition.

Delete the four fixed IDs in reverse dependency order:

curl -ks -o /dev/null -w '%{http_code}\n' -X DELETE "${API7_ADMIN_URL}/apisix/admin/consumers/basic-auth-consumer/credentials/basic-auth-consumer-cred?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -H "X-API-KEY: ${API7_ADMIN_KEY}"
curl -ks -o /dev/null -w '%{http_code}\n' -X DELETE "${API7_ADMIN_URL}/apisix/admin/consumers/basic-auth-consumer?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -H "X-API-KEY: ${API7_ADMIN_KEY}"
curl -ks -o /dev/null -w '%{http_code}\n' -X DELETE "${API7_ADMIN_URL}/apisix/admin/routes/basic-auth-route?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -H "X-API-KEY: ${API7_ADMIN_KEY}"
curl -ks -o /dev/null -w '%{http_code}\n' -X DELETE "${API7_ADMIN_URL}/apisix/admin/services/basic-auth-httpbin-service?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -H "X-API-KEY: ${API7_ADMIN_KEY}"

Expected: each command prints 200.

Save an empty desired state for this guide's label partition:

basic-auth-cleanup.yaml

services: []
consumers: []

Lint it and review the deletions before applying them:

adc lint -f basic-auth-cleanup.yaml
adc diff -f basic-auth-cleanup.yaml --backend api7ee --server "${API7_ADMIN_URL}" --token "${API7_ADMIN_KEY}" --gateway-group "${API7_GATEWAY_GROUP_NAME}" --tls-skip-verify --label-selector guide=basic-auth

Expected: the diff deletes only the service, its nested route, the consumer, and credential created under guide=basic-auth. Stop if it lists anything else.

adc sync -f basic-auth-cleanup.yaml --backend api7ee --server "${API7_ADMIN_URL}" --token "${API7_ADMIN_KEY}" --gateway-group "${API7_GATEWAY_GROUP_NAME}" --tls-skip-verify --label-selector guide=basic-auth

Expected: ADC removes only the reviewed resources in this label partition.

After cleanup, the example route no longer handles /anything/basic-auth. Another route can still match that path, so the data-plane response is not guaranteed to be 404.

Remove only the local example files you saved:

rm -f basic-auth-adc.yaml basic-auth-cleanup.yaml diff.yaml

Expected: no output.

Troubleshoot

Symptom	Cause	Fix
The request returns `401`. `{"message":"Missing authorization in request"}` means the header is absent; `{"message":"Invalid user authorization"}` means the credential did not resolve.	The request lacks Basic credentials, or the username or password differs from step 3.	Send `-u alice:secret-password`; if it still fails, compare both values and wait a few seconds after credential creation.
`404`.	The route is absent from this gateway instance or belongs to another group.	Verify `API7_GATEWAY_GROUP_ID`, confirm an instance is `Healthy`, and retry after propagation.
ADC proposes unrelated changes.	The selector is missing or another resource uses the same guide label.	Stop before `sync`; use the exact selector and reserve `guide=basic-auth` for this example.

basic-auth plugin reference (opens in Plugin Hub docs) — review every plugin field and advanced behavior.
Consumers and credentials — understand how credentials resolve to consumer identities.
Configure JWT authentication — protect a route with signed tokens instead of passwords.