a7-plugin-basic-auth

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. API7 EE 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 the database.

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

1. Create a consumer

a7 consumer create -g default -f - <<'EOF'
{
  "username": "alice"
}
EOF

2. Add basic-auth credential

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

3. Create a route with basic-auth enabled

a7 route create -g default -f - <<'EOF'
{
  "id": "basic-protected",
  "uri": "/api/*",
  "plugins": {
    "basic-auth": {}
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 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

a7 consumer create -g default -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"
gateway_groups:
  - name: default
    consumers:
      - username: alice
    routes:
      - id: basic-protected
        uri: /api/*
        plugins:
          basic-auth: {}
        upstream:
          type: roundrobin
          nodes:
            - host: backend
              port: 8080
              weight: 1

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

---

This page is generated from a7-plugin-basic-auth/SKILL.md in the api7/a7 repository. Browse all skills on the AI Agent Skills page.