Basic HTTP Authentication

SWS provides 'Basic' HTTP Authentication Scheme using an user:password pair.

This feature is disabled by default and can be controlled by the string --basic-auth option or the equivalent SERVER_BASIC_AUTH env.

The format to use is the following:

username:encrypted_password

Both are separated by a : (punctuation mark) character.

Password Encryption

Only the password must be encoded using the BCrypt password-hashing function.

Bcrypt Password Length Limit

SWS rejects passwords longer than 72 bytes before bcrypt verification. Hashes generated with standard bcrypt utilities or the Apache htpasswd tool are compatible with SWS for passwords of 72 bytes or fewer.

Passwords longer than 72 bytes will not match in SWS, even if the hash was generated by a tool that truncates the password.

Make sure your password is at most 72 bytes long. We recommend using ASCII-only passwords of 72 characters or fewer to avoid encoding issues.

As an example, we will use the Apache htpasswd tool to generate the username:encrypted_password pair.

htpasswd -nBC10 "username"
# New password:
# Re-type new password:
# username:$2y$10$8phm28BB4YpKPDjOpdTT8eUcfVDw0xc85VZPxg2zae1GR8EQqus3i

Password Security Advice

The password verification happens at runtime but its verification speed depends on the computing time cost of bcrypt algorithm used.

For example, the htpasswd tool supports a -C argument to adjust the bcrypt's computing time.

Using a higher value is more secure but slower. The default value is 5 and the possible values are ranging from 4 to 17.

Docker Compose Advice

If you are using SERVER_BASIC_AUTH env via a docker-compose.yml file don't forget to replace the single $ (dollar sign) with a $$ (double-dollar sign) if you want those individual $ dollar signs in your configuration to be treated by Docker as literals.
More details in the Docker Compose file: variable substitution page.

Finally, assign the credentials and run the server.

static-web-server \
    --port 8787 \
    --root ./my-public-dir \
    --basic-auth 'username:$2y$10$8phm28BB4YpKPDjOpdTT8eUcfVDw0xc85VZPxg2zae1GR8EQqus3i'