basic-auth

The basic-auth plugin adds basic access authentication for clients to authenticate themselves before being able to access upstream resources.

Examples​

The examples below demonstrate how you can work with the basic-auth plugin for different scenarios.

Implement Basic Authentication on Route​

The following example demonstrates how to implement basic authentication on a route.

Create a consumer with basic-auth and configure the credentials:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "johndoe",
    "plugins": {
      "basic-auth": {
        "username": "johndoe",
        "password": "john-key"
      }
    }
  }'

Create a route with basic-auth:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "basic-auth-route",
    "uri": "/anything",
    "plugins": {
      "basic-auth": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Verify with a Valid Key​

Send a request to with the valid key:

curl -i "http://127.0.0.1:9080/anything" -u johndoe:john-key

You should receive an HTTP/1.1 200 OK response.

Verify with an Invalid Key​

Send a request with an invalid key:

curl -i "http://127.0.0.1:9080/anything" -u johndoe:invalid-key

You should see an HTTP/1.1 401 Unauthorized response with the following:

{"message":"Invalid user authorization"}

Verify without a Key​

Send a request to without a key:

curl -i "http://127.0.0.1:9080/anything"

You should see an HTTP/1.1 401 Unauthorized response with the following:

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

Hide Authentication Information From Upstream​

The following example demonstrates how to prevent the key from being sent to the upstream services by configuring hide_credentials. By default, the authentication key is forwarded to the upstream services, which might lead to security risks in some circumstances.

Create a consumer with basic-auth and configure key auth credentials:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "username": "johndoe",
  "plugins": {
    "basic-auth": {
      "username": "johndoe",
      "password": "john-key"
    }
  }
}'

Without Hiding Credentials​

Create a route with basic-auth and configure hide_credentials to false, which is the default configuration:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "id": "basic-auth-route",
  "uri": "/anything",
  "plugins": {
    "basic-auth": {
      "hide_credentials": false
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

Send a request with the valid key:

curl -i "http://127.0.0.1:9080/anything" -u johndoe:john-key

You should see an HTTP/1.1 200 OK response with the following:

{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Authorization": "Basic am9obmRvZTpqb2huLWtleQ==", 
    "Host": "127.0.0.1", 
    "User-Agent": "curl/8.6.0", 
    "X-Amzn-Trace-Id": "Root=1-66cc2195-22bd5f401b13480e63c498c6", 
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  "json": null, 
  "method": "GET", 
  "origin": "192.168.65.1, 43.228.226.23", 
  "url": "http://127.0.0.1/anything"
}

Note that the credentials are visible to the upstream service in base64-encoded format.

curl -i "http://127.0.0.1:9080/anything" -H "Authorization: Basic am9obmRvZTpqb2huLWtleQ=="

Hide Credentials​

Update the plugin's hide_credentials to true:

curl "http://127.0.0.1:9180/apisix/admin/routes/basic-auth-route" -X PATCH \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "plugins": {
    "basic-auth": {
      "hide_credentials": true
    }
  }
}'

Send a request with the valid key:

curl -i "http://127.0.0.1:9080/anything" -u johndoe:john-key

You should see an HTTP/1.1 200 OK response with the following:

{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Host": "127.0.0.1", 
    "User-Agent": "curl/8.6.0", 
    "X-Amzn-Trace-Id": "Root=1-66cc21a7-4f6ac87946e25f325167d53a", 
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  "json": null, 
  "method": "GET", 
  "origin": "192.168.65.1, 43.228.226.23", 
  "url": "http://127.0.0.1/anything"
}

Note that the credentials are no longer visible to the upstream service.