Basic Authentication

This guide provides instructions for configuring HTTP Basic authentication. HTTP Basic authentication checks if an incoming request has a valid username and password before routing the request to a backend service.

Envoy Gateway introduces a new CRD called SecurityPolicy that allows the user to configure HTTP Basic authentication. This instantiated resource can be linked to a Gateway, HTTPRoute or GRPCRoute resource.


Follow the steps from the Quickstart guide to install Envoy Gateway and the example manifest. Before proceeding, you should be able to query the example backend using HTTP.


Envoy Gateway uses .htpasswd format to store the username-password pairs for authentication. The file must be stored in a kubernetes secret and referenced in the SecurityPolicy configuration. The secret is an Opaque secret, and the username-password pairs must be stored in the key “.htpasswd”.

Create a .htpasswd file

First, create a .htpasswd file with the username and password you want to use for authentication.

The input password won’t be saved, instead, a hash will be generated and saved in the output file. When a request tries to access protected resources, the password in the “Authorization” HTTP header will be hashed and compared with the saved hash.

Note: only SHA hash algorithm is supported for now.

$ htpasswd -cbs .htpasswd foo bar
Adding password for user foo

You can also add more users to the file:

$ htpasswd -bs .htpasswd foo1 bar1

Create a kubernetes secret

Next, create a kubernetes secret with the generated .htpasswd file in the previous step.

$ kubectl create secret generic basic-auth --from-file=.htpasswd
secret "basic-auth" created

Create a SecurityPolicy

The below example defines a SecurityPolicy that authenticates requests against the user list in the kubernetes secret generated in the previous step.

cat <<EOF | kubectl apply -f -
kind: SecurityPolicy
  name: basic-auth-example
    kind: HTTPRoute
    name: backend
      name: "basic-auth"

Verify the SecurityPolicy configuration:

kubectl get securitypolicy/basic-auth-example -o yaml


Ensure the GATEWAY_HOST environment variable from the Quickstart guide is set. If not, follow the Quickstart instructions to set the variable.


Send a request to the backend service without Authentication header:

curl -v -H "Host:" "http://${GATEWAY_HOST}/"

You should see 401 Unauthorized in the response, indicating that the request is not allowed without authentication.

< HTTP/1.1 401 Unauthorized
< content-length: 58
< content-type: text/plain
< date: Tue, 28 Nov 2023 12:43:32 GMT
< server: envoy
* Connection #0 to host left intact
User authentication failed. Missing username and password.

Send a request to the backend service with Authentication header:

curl -v -H "Host:" -u 'foo:bar' "http://${GATEWAY_HOST}/"

The request should be allowed and you should see the response from the backend service.

## Clean-Up

Follow the steps from the [Quickstart](../quickstart) guide to uninstall Envoy Gateway and the example manifest.

Delete the SecurityPolicy and the secret

kubectl delete securitypolicy/basic-auth-example
kubectl delete secret/basic-auth

Next Steps

Checkout the Developer Guide to get involved in the project.