HAProxy Enterprise Documentation 2.3r1

Userlist

The userlist section allows you to configure authentication and restrict access to proxied services only for the defined users. Currently only http Basic authentication is supported.

Each userlist keyword is followed by a label, such as valid_users, to differentiate it from others. The label can be used by ACLs and other HAProxy Enterprise keywords.

userlist valid_users
   # Your configuration directives

In our examples we will not be using ACLs because they are talked about and explained in depth at a later topic, but, it is always good practice to use ACL's.

Userlist section examples

In following configuration sample we have defined frontend www and use the http-request auth keyword which stops the evaluation of further rules and immediately asks for a user name and a password.

We have also defined a userlist section labeled basic_auth_logins and added two users with a basic text password for each. The http_auth fetch returns a Boolean result indicating whether the username and password that were received matches the ones defined in the basic_auth_logins userlist.

frontend www
  bind :80
  bind :443 ssl crt /etc/ssl/certs/site.pem
  http-request redirect scheme https unless { ssl_fc }
  http-request auth unless { http_auth(basic_auth_logins) }

userlist basic_auth_logins
  user joe insecure-password mypassword123
  user jane insecure-password myotherpassword123

Each user line specifies a username, the type of password that will be used, and password that HAProxy Enterprise will accept.

Note

Users defined in a userlist are not mapped to any Linux system users and exist only in the configuration file.

Using encrypted passwords

Changing insecure-password to password allows you to use encrypted passwords.

frontend www
  bind :80
  bind :443 ssl crt /etc/ssl/certs/site.pem
  http-request redirect scheme https unless { ssl_fc }
  http-request auth unless { http_auth(basic_auth_logins) }

userlist basic_auth_logins
  user joe password $5$s6Subz0X7FSX2zON$r94OtF6gOfWlGmySwvn3pDFIAHbIpe6mWneueqtBOm/
  user jane password ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Tip

Use the following commands to generate a SHA-256 encrypted password.

$ sudo apt install whois
$ mkpasswd -m sha-256 mypassword123

$5$s6Subz0X7FSX2zON$r94OtF6gOfWlGmySwvn3pDFIAHbIpe6mWneueqtBOm/

Splitting users into groups

Users can also be added in groups. Building on our example we have used the group keyword to define two groups, labeled admins and devops. We also changed http_auth to http_auth_group. The http_auth_group fetch will return a Boolean if username and password are found in the userlist for groups admins and devops.

frontend www
  bind :80
  bind :443 ssl crt /etc/ssl/certs/site.pem
  http-request redirect scheme https unless { ssl_fc }
  http-request auth unless { http_auth_group(basic_auth_logins) admins devops }

userlist basic_auth_logins
  group admins  users joe,jane
  group devops  users joe

  user joe password $5$s6Subz0X7FSX2zON$r94OtF6gOfWlGmySwvn3pDFIAHbIpe6mWneueqtBOm/
  user jane password ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Next up

Cache