Managing multiple htpasswd users with the Ingress-Nginx’s auth-map annotation

I was asked to add multiple https://httpd.apache.org/docs/2.4/programs/htpasswd.html">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 https://github.com/kubernetes/ingress-nginx">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.

Pre-requisites

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

num,username,password1,john,random012,smith,random02

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.

touch hash.sh;chmod +x ./hash.sh

Add the following code:

#!/bin/bashed -s $1 <<< wexec < $1read headerwhile IFS="," read -r num username passworddo    hashed=`openssl passwd -quiet $password`    echo "$username: $hashed"done

To explain how it works:

• exec < $1 allows us to pass in a file path as an argument.

• ed -s $1 <<< w adds 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 $password creates a simple md5 hashed password. The -quiet is because of a truncation error warning that's irrelevant if the password is 8 characters or less.

• $username: $hashed is 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.

./hash.sh ./passwords.csv

The output will look something like this.

john: XQIeryMOkCNpksmith: gB1FNtHU3drCA

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 stringData property.

apiVersion: v1kind: Secrettype: Opaquemetadata:  name: secret-filestringData:  john: XQIeryMOkCNpk  smith: gB1FNtHU3drCA

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.

kind: Ingressmetadata:  name: project-ingress  annotations:        nginx.ingress.kubernetes.io/auth-type: basic    nginx.ingress.kubernetes.io/auth-secret: secret-file    nginx.ingress.kubernetes.io/auth-secret-type: auth-map    nginx.ingress.kubernetes.io/auth-realm: "Progress Authentication"    #...etc

• nginx.ingress.kubernetes.io/auth-type: basic tells the ingress to use Basic authentication versus Digest auth.

• nginx.ingress.kubernetes.io/auth-secret: secret-file is the name of our secrets file which we defined earlier.

• nginx.ingress.kubernetes.io/auth-secret-type: auth-map tells 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.

https://cdn.hashnode.com/res/hashnode/image/upload/v1679079003107/0cc99cb0-bbb7-4168-8893-33bf68a9326f.png" alt class="image--center mx-auto" />

If you're testing via the GUI, you may want to use Roland Toth's advice to https://blog.rolandtoth.hu/logout-from-htpasswd-protected-site/">log out:

http://logout@example.com/

Alternatively, you can test authentication through curl or https://httpie.io/">httpie:

http https://example.comhttp https://example.com --auth username:password

Signing out

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.

Additional resources

https://github.com/kubernetes/ingress-nginx/issues/5858">https://github.com/kubernetes/ingress-nginx/issues/5858

https://github.com/kubernetes/ingress-nginx/pull/4560">https://github.com/kubernetes/ingress-nginx/pull/4560