a6-plugin-basic-auth

name: a6-plugin-basic-auth description: >- Skill for configuring the Apache APISIX basic-auth plugin via the a6 CLI. Covers HTTP Basic Authentication setup on routes, consumer credential binding with username/password, hide_credentials, anonymous consumer fallback, and common operational patterns. version: "1.0.0" author: Apache APISIX Contributors license: Apache-2.0 metadata: category: plugin apisix_version: ">=3.0.0" plugin_name: basic-auth a6_commands: - a6 route create - a6 route update - a6 consumer create - a6 consumer update

Overview

The basic-auth plugin authenticates requests using HTTP Basic Authentication (RFC 7617). Consumers register a username and password. Clients send credentials in the Authorization: Basic <base64> header. APISIX decodes and validates against consumer credentials, then forwards the request with consumer identity headers.

When to Use

Simple username/password authentication for APIs
Quick protection for internal or development APIs
Integration with tools that natively support HTTP Basic Auth (browsers, curl, Postman)

Plugin Configuration Reference (Route/Service)

Field	Type	Required	Default	Description
`hide_credentials`	boolean	No	`false`	Remove `Authorization` header before forwarding upstream
`anonymous_consumer`	string	No	—	Consumer username for unauthenticated requests
`realm`	string	No	`"basic"`	Realm in `WWW-Authenticate` response header on 401

Consumer Credential Reference

Field	Type	Required	Description
`username`	string	Yes	Unique username for the consumer
`password`	string	Yes	Password for the consumer. Auto-encrypted in etcd.

Step-by-Step: Enable basic-auth on a Route

1. Create a consumer

a6 consumer create -f - <<'EOF'
{
  "username": "alice"
}
EOF

2. Add basic-auth credential

curl "$(a6 context current -o json | jq -r .server)/apisix/admin/consumers/alice/credentials" \
  -X PUT \
  -H "X-API-KEY: $(a6 context current -o json | jq -r .api_key)" \
  -d '{
    "id": "cred-alice-basic-auth",
    "plugins": {
      "basic-auth": {
        "username": "alice",
        "password": "alice-password-123"
      }
    }
  }'

3. Create a route with basic-auth enabled

a6 route create -f - <<'EOF'
{
  "id": "basic-protected",
  "uri": "/api/*",
  "plugins": {
    "basic-auth": {}
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "backend:8080": 1
    }
  }
}
EOF

4. Verify authentication

# Using curl -u flag (sends Authorization: Basic header)
curl -i http://127.0.0.1:9080/api/users -u alice:alice-password-123

# Using explicit header (base64 of "alice:alice-password-123")
curl -i http://127.0.0.1:9080/api/users \
  -H "Authorization: Basic YWxpY2U6YWxpY2UtcGFzc3dvcmQtMTIz"

# Should fail (401)
curl -i http://127.0.0.1:9080/api/users

Common Patterns

Hide credentials from upstream

{
  "plugins": {
    "basic-auth": {
      "hide_credentials": true
    }
  }
}

The Authorization header is stripped before reaching the backend. Always enable this in production to prevent credential leakage.

Anonymous consumer with rate limiting

a6 consumer create -f - <<'EOF'
{
  "username": "anonymous",
  "plugins": {
    "limit-count": {
      "count": 10,
      "time_window": 60,
      "rejected_code": 429
    }
  }
}
EOF

{
  "plugins": {
    "basic-auth": {
      "anonymous_consumer": "anonymous"
    }
  }
}

Requests with valid credentials → authenticated consumer. Requests without credentials → anonymous consumer with rate limits.

Headers Added to Upstream

Header	Value
`X-Consumer-Username`	Consumer's username
`X-Credential-Identifier`	Credential ID
`X-Consumer-Custom-Id`	Consumer's `labels.custom_id` (if set)
`Authorization`	Original header (unless `hide_credentials: true`)

Troubleshooting

Symptom	Cause	Fix
`401 Unauthorized`	Missing or wrong credentials	Check username/password; ensure base64 encoding is correct
Credentials visible in upstream logs	`hide_credentials` is false	Set `hide_credentials: true`
Browser not prompting login dialog	Missing `WWW-Authenticate` header	Verify plugin is enabled; check `realm` setting
Anonymous users not working	`anonymous_consumer` not set	Create consumer and set the field on the route plugin

Config Sync Example

version: "1"
consumers:
  - username: alice
routes:
  - id: basic-protected
    uri: /api/*
    plugins:
      basic-auth: {}
    upstream_id: my-upstream
upstreams:
  - id: my-upstream
    type: roundrobin
    nodes:
      "backend:8080": 1

Note: Consumer credentials (username/password) must be created separately via the Admin API; a6 config sync manages the consumer resource but credentials are sub-resources.