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

Replace <gateway-group-id> with the ID returned by a7 gateway-group list -o json.

1. Create a consumer

a7 consumer create -g <gateway-group-id> -f - <<'EOF'
{
  "username": "alice"
}
EOF

2. Add basic-auth credential

a7 credential create cred-alice-basic-auth -g <gateway-group-id> \
  --consumer alice \
  --plugins-json '{"basic-auth":{"username":"alice","password":"alice-password-123"}}'

3. Create a service and route with basic-auth enabled

a7 service create -g <gateway-group-id> -f - <<'EOF'
{
  "id": "basic-protected-service",
  "name": "Basic protected service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

a7 route create -g <gateway-group-id> -f - <<'EOF'
{
  "id": "basic-protected",
  "paths": ["/api/*"],
  "service_id": "basic-protected-service",
  "plugins": {
    "basic-auth": {}
  }
}
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 <gateway-group-id> -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

Save the following as basic-auth.yaml:

version: "1"
services:
  - id: basic-protected-service
    name: Basic protected service
    upstream:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1
routes:
  - id: basic-protected
    name: Basic protected route
    paths:
      - /api/*
    service_id: basic-protected-service
    plugins:
      basic-auth: {}

Validate and apply this partial configuration to the target gateway group:

a7 config validate -f basic-auth.yaml
a7 config sync -g <gateway-group-id> -f basic-auth.yaml --delete=false

Note: Create the consumer and credential separately with a7 consumer create and a7 credential create. Config Sync manages only the service and route in this example. Disabling deletion preserves other resources that are not included in this partial configuration.

---

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.