4.5 Authentication

Along with access control lists, introduced above (see ACL), authentication provides another way to limit access to certain services. Pound supports basic authentication, as defined in RFC 7617.

This authentication method relies on the presence of the Authorization header in the HTTP request. If the header is present, its value specifies the ‘Basic’ authorization method and contains credentials (username and password) that match one of the users from the server user database, the request is accepted. Otherwise a 401 (‘Authentication Required’) or 407 (‘Proxy Authentication Required’) response is returned with the WWW-Authenticate header requesting basic authentication.

The BasicAuth conditional statement verifies if the Authorization header is present and provides correct credentials. The statement matches the request if so.

The BasicAuth statement takes a single argument, specifying the name of a file containing user database. This is a plain-text file created with htpasswd or similar utility, i.e. each non-empty line of it must contain username and password hash separated by a colon. Password hash can be one of:

• Password in plain text.
• Hash created by the system crypt(3) function.
• Password hashed using SHA1 algorithm and encoded in BASE64. This hash must be prefixed by ‘{SHA}’.
• Apache-style ‘APR1’ hash.

Password file is read at startup, after which its contents is stored in memory. Pound will re-read it if it notices that the file has changed, so you need not restart the daemon if you do any changes to the file.

Thus, if you put the BasicAuth statement in each service that must be accessible to authorized users only, that would do the first and principal part of the basic authentication scheme: access control. There remains second part: returning properly formatted 401 response if the request did not pass authorization. That can be done using a combination of the Error internal backend (see Error responses) and response modification techniques described in the previous section.

However, instead of using BasicAuth in each service requiring limited access and placing a service generating the 401 response in the end, it is simpler and less error-prone to use the following approach:

Create a service with the following content:

Service
    Not BasicAuth "pound/htpasswd"
    Rewrite response
        SetHeader "WWW-Authenticate: Basic realm=\"Restricted access\""
    End
    Error 401
End

Replace the file name (pound/htpasswd) and realm name (‘Restricted access’) with the actual values.

Make sure that all services that need to be protected by basic authentication are declared after that service. This way, any request that does not convey an Authentication header with credentials matching an entry from your password file will match this service, and will be replied to with a properly formatted 401 response, which will prompt the remote user to authenticate themselves. On the other hand, authorized requests will not match this service and will eventually be handled by one of the services declared after it.