/ #rancher #nginx 

Basic auth with nginx ingress in rancher

It’s old but effective. When playing around with new things, putting them on the server, giving access to a few friends you may come to the point of thinking:

“Hm… What if someone else would find this link?”

Well we have a solution for that for a while now. HTTP Authentication. Whenever someone tries to access the page, the server will ask for authentication. A username and password must be given, and the server validates it. The browser can remember the credentials to make it more convenient.

You should **never** use this method **without https**! The credentials are (for "basic auth") just base64 encoded, so it's very easy to just grab and read the credentials from your network traffic.
Another word of warning: Don't use it to protect important information on production systems. At least not without additional care-taking. By default there's no brute-force protection/alerting so bots could just try breaking it without you noticing.
More danger! 

How to setup basic auth with rancher

Credentials secret

First you need to create a credentials secret. Browse to “Resources/Secrets” in the project you want to have the basic auth enabled and add a new secret there. Name doesn’t matter, but you need to write it down because you’ll need to use it in the annotations later. We will use “htpasswd” here.

The secret should have one key auth. It’s important to name it exactly like that, lowercase.

As value you can pass the credentials. The format is the same as “htpasswd” file. You can create them using command line tool “htpasswd” (coming with apache utils on most distries) or use something like this.

It should be obvious, but: Please don't use password generator websites for important stuff :). You never know where/how they save the passwords...
It's obvious! 

Load balancer

Usually you will use the ingress load balancers (level 7 load balancer) to give access to your endpoints and for dealing with https. Luckily they also support the basic auth, so all we have to do is put some annotations there:

Just add those three annotations
Just add those three annotations

Here the keys for easy copying:

  • The auth-realm is the message being displayed in the browser dialog opening and asking for password/name.
  • auth-type defines what type to use, easiest is “basic”
  • auth-secret defines what secret to use for the credentials, we use htpasswd here as defined in previous step.

If you use the yml configuration, it will look like this:

apiVersion: extensions/v1beta1
kind: Ingress
    certmanager.k8s.io/cluster-issuer: letsencrypt-prod
    kubernetes.io/tls-acme: '"true"'
    nginx.ingress.kubernetes.io/auth-realm: Authentication Required
    nginx.ingress.kubernetes.io/auth-secret: htpasswd
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/proxy-body-size: 512m
  creationTimestamp: 2018-12-01T16:45:28Z
--- more stuff down here ---

What could go wrong?

When doing this first time, I had the glorious idea of putting the auth-realm into quotes - like "Authentication Required". Unfortunately that won't work. And you might not notice immediately why...
I feel stupid now 

The template it generates for the nginx config uses quotes itself. So with your quotes and the normal quotes of nginx, you get something like that in the resulting nginx file:

auth_basic ""Authentication Required"";

which of course is not valid. However the load balancer will still work as nginx refuses to load new (invalid) config.

After too much time of searching, I found the problem in the logs of the nginx-ingress-controller service. You can find that one in your “System” project.

View logs of this nginx-ingress-controller if something is fishy
View logs of this nginx-ingress-controller if something is fishy

That’s it!

In theory it’s easy, and if you don’t add the quotes, it shouldn’t take long to setup your basic auth! Happy if this article will save someone from the mistake I made :D or at least preventing me from doing the same mistake again.




Passionate coder; discovered the black magic of writing programs in the age of 13 and still loving it. When not fighting with bits & bytes probably seen outside with a camera.