Managing multiple htpasswd users with the Ingress-Nginx's auth-map annotation
I was asked to add multiple htpasswd users to a temporary demo service in Kubernetes. It took a little time to find the relevant documentation, so I decided to write this article (at least for my future self to remember).
The Kubernetes Nginx Ingress has an auth-file annotation which is excellent for single-user credentials, but the auth-map annotation was designed for easily adding multiple users.
Disclaimer: I'm on MacOS. So the commands may not work the same on a different operating system. Hopefully, the process can be replicated.
In this article, I'll share:
A way to generate the htpasswd usernames and hashed passwords
How to define a multi-user htpasswd manifest yaml for the ingress nginx
How to configure the Ingress Nginx auth-map annotation.
You need a K8s cluster setup with an Ingress Nginx
You need a deployment and service to hide behind an htpasswd.
Step 1. Creating a list of usernames and passwords
You could autogenerate user names in any way you like. I used a website to generate passwords and a spreadsheet to collate them.
Nonetheless, we're good to go as long as you have a simple CSV file with the following columns.
Note, in our version, the password should be 8 characters or less due to using the md5 hash.
Step 2. Generating the hashed passwords
Create a bash file.
chmod +x ./hash.sh
Add the following code:
ed -s $1 <<< w
exec < $1
while IFS="," read -r num username password
hashed=`openssl passwd -quiet $password`
echo "$username: $hashed"
To explain how it works:
exec < $1allows us to pass in a file path as an argument.
ed -s $1 <<< wadds an extra line to the end of the CSV if one doesn't exist. This is to ensure when we loop over the CSV rows, we loop over every row. Otherwise, it will miss the final row in the spreadsheet.
openssl passwd -quiet $passwordcreates a simple md5 hashed password. The
-quietis because of a truncation error warning that's irrelevant if the password is 8 characters or less.
$username: $hashedis just so we have something we can copy-paste into our Kubernetes secret file
Now, we can run the
hash.sh script to generate the passwords.
The output will look something like this.
Step 3. Creating the Kubernetes secret file
We can take the output of the
hash.sh command and add the key-value pairs under the
You want to apply the secret file to the cluster.
kubectl apply -f <secret-file-path>
Step 4. Configuring the ingress
Now we have our usernames and passwords configured in a Kubernetes secret file, we need to attach them to the ingress. Add the following annotations to the ingress.
nginx.ingress.kubernetes.io/auth-realm: "Progress Authentication"
nginx.ingress.kubernetes.io/auth-type: basictells the ingress to use Basic authentication versus Digest auth.
nginx.ingress.kubernetes.io/auth-secret: secret-fileis the name of our secrets file which we defined earlier.
nginx.ingress.kubernetes.io/auth-secret-type: auth-maptells the ingress to interpret the secrets a list of usernames and hashed passwords versus a single htpasswd file.
nginx.ingress.kubernetes.io/auth-realm: "Progress Authentication"returns a
WWW-Authenticate"header with whatever value you define.
Finally, you want to apply your ingress.
kubectl apply -f <ingress-file-path>
Step 5. Testing the login
Now, when you visit the page, you'll be presented with a sign-in form, of which, you can test the credentials.
If you're testing via the GUI, you may want to use Roland Toth's advice to log out:
Alternatively, you can test authentication through curl or httpie:
http https://example.com --auth username:password
If you're looking for a robust sign-in solution, perhaps
htpasswd isn't as ideal as implementing or using an existing email-based username and password system. But for hiding functionality in testing environments that only a few people need access to, it's a handy and quick way to add protection to your website.
Did you find this article valuable?
Support Gemma Black by becoming a sponsor. Any amount is appreciated!