moonming/a6-plugin-basic-auth

a6-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. 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.