Basic authentication

When your traffic is HTTP, you can use basic authentication to display a login prompt to users. Configuring it is easy, but it does have one drawback: credentials are transmitted in the clear over HTTP. You can mitigate this exposure by enabling TLS to encrypt the traffic. In our examples, we will do just that.

Enable basic authentication Jump to heading #

Follow these steps to set up basic authentication:

1. Usernames and their associated passwords are stored in the load balancer’s running memory.

   To define them, create a userlist section. Each entry in this section has a user argument to indicate the username and an insecure-password argument to indicate the password.

   haproxy
   userlist mycredentials
     user joe   insecure-password joespassword
     user alice insecure-password alicespassword
     user mark  insecure-password markspassword

   haproxy
   userlist mycredentials
     user joe   insecure-password joespassword
     user alice insecure-password alicespassword
     user mark  insecure-password markspassword

2. In your frontend section, enable TLS on your bind line so that credentials will be encrypted when transmitted between the client and load balancer.

   In this example, we also redirect HTTP requests to HTTPS. We use the http-request auth line to display the basic authentication login prompt to users. If a user has already logged in, then they won’t see the prompt again.

   haproxy
   frontend www
     bind :80
     bind :443 ssl crt /site.pem
     http-request redirect scheme https unless { ssl_fc }
     http-request auth unless { http_auth(mycredentials) }
     default_backend webservers

   haproxy
   frontend www
     bind :80
     bind :443 ssl crt /site.pem
     http-request redirect scheme https unless { ssl_fc }
     http-request auth unless { http_auth(mycredentials) }
     default_backend webservers

Hash passwords in the userlist Jump to heading #

You can store a hashed value for a password in the userlist section instead of storing it as cleartext.

1. Install the mkpasswd tool:

   apt yum

   nix
   # mkpasswd is included in the whois package
   sudo apt install whois

   nix
   # mkpasswd is included in the whois package
   sudo apt install whois

   nix
   sudo yum install mkpasswd

   nix
   sudo yum install mkpasswd

2. Call mkpasswd with the SHA-256 algorithm to hash your password:

   nix
   mkpasswd -m sha-256 mypassword123

   nix
   mkpasswd -m sha-256 mypassword123

   output
   text
   $5$s6Subz0X7FSX2zON$r94OtF6gOfWlGmySwvn3pDFIAHbIpe6mWneueqtBOm/

   output
   text
   $5$s6Subz0X7FSX2zON$r94OtF6gOfWlGmySwvn3pDFIAHbIpe6mWneueqtBOm/

3. Store the hashed password by using the password argument:

   haproxy
   userlist mycredentials
     user joe password $5$s6Subz0X7FSX2zON$r94OtF6gOfWlGmySwvn3pDFIAHbIpe6mWneueqtBOm/

   haproxy
   userlist mycredentials
     user joe password $5$s6Subz0X7FSX2zON$r94OtF6gOfWlGmySwvn3pDFIAHbIpe6mWneueqtBOm/

See also Jump to heading #

For complete information on these directives related to authentication, see the HAProxy Configuration Manual:

• Specify the port for incoming traffic: bind
• Prompt the user to authenticate: http-request auth
• Specify accepted usernames and passwords: userlists