WL#12503: Authentication for HTTP component
The HTTP component of the MySQL Router (WL#11891) provides basic HTTP support.
Authentication for HTTP as defined by RFC 7235 is need to protect resources exposed by the HTTP component to authenticated users.
While HTTP specifies several Authentication methods "Basic" RFC 7617 is the most widely supported and allows most flexible integration with credential stores.
Note: Digest Authentication also exists (RFC 7616), but only the insecure "MD5" method is widely supported by clients.
- Credentials stored by the HTTP Component MUST be stored securely.
- Follow RFC 7617 and RFC 7235 to integrate with existing HTTP clients.
- Credential store must be managable independent of a running HTTP component.
- Allow authentication via Basic Authentication RFC 7617
- Allow authentication against a secure, file based password storage
- Provide a standalone tool to manage secure, file based password storage
- "Authorization" header MUST be parsed by server-side according to RFC 7617
- "WWW-Authenticate" header MUST be generated by server-side according to RFC 7617
- file-based storage of credentials SHOULD NOT be hashed by broken hash algorithms.
- if a username exists more than once in the file-storage, only the first entry MUST be used.
- if hash-spec is not supported authentication MUST fail in the same way as if the password wouldn't match.
- invalid authentication methods in the configuration MUST lead to failure to start
- file-based storage of credentials MUST be only read/write-able by the router user and router group.
- MUST be able to add sha256_crypt hashed passwords to passwd file
- MUST be able to add sha512_crypt hashed passwords to passwd file
- MUST accepted passwords via stdin only
- MUST be able to verify sha256_crypt hashed passwords against passwd file
- MUST be able to verify sha512_crypt hashed passwords against passwd file
- MUST be able to delete accounts from passwd file
- MUST be able to list all accounts
- MUST be able to list accounts by username
password file format
- one line per username:hashed-password-spec
- each username should be unique, duplicating usernames are ignored
- hashed-password-spec follows https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md
- supported Key Derivation Functions
Note: similar to /etc/shadow and htpasswd
In HTTP a server tells a client that authentication is required with:
HTTP/1.1 401 Unauthenticated WWW-Authenticate: Basic realm="..." ...
A client answers with:
GET / HTTP/1.1 Authorization: Basic ....
The credentials provided by the client are decoded according to the Authentication Method's spec. For Basic Authentication, the payload of the Authorization header is Base64 encoded(username:password).
If Authorization failed, "403 Forbidden" is returned, otherwise the request is processed.
File Authentication Backend
The credentials provided by a authentication method are verified against a authentication backend.
The file backend verifies credentials against a passwd-like file that is expected to be in "password file format" specified above.
Zero or more HTTP authentication backends may be specified in the configuration:
[http_auth_backend:local] backend=file filename=passwd
- name of the backend implementation: file
- name of the storage for backend. Relative to data_folder
Zero or more realms may be specified in the configuration:
[http_auth_realm:secure_api] backend=local method=basic name=API require=valid-user
- name of the http_auth_backend section
- optional, "valid-user", default valid-user. "valid-user" checks requires a provided user validates with the authentication backend.
- name of the realm presented to authenticated user
Realm of Server
The HTTP-server component described in WL#11891 gets extended by
[http_server] port=8000 require_realm=secure_api
- name of a http_auth_realm instance.
mysqlrouter_passwd is a new command line application to manage the accounts in the passwd file.
Set (add or replace) account made up of username and hashed password that was taken from stdin to file.
- required options
- 0 on success, 1 on error
Check if password passed through stdin matches the hash stored in the file.
- required options
--verify filename username
- 0 on success, 1 if not verification failed.
Delete an account matched by username from file.
- required options
--delete filename username
- 0 on success, 1 on failure (username not found, ...)
List one or all accounts in "password file format".
- required options
- optional username
--list filename username
- 0 on success, 1 on failure (username not found, file not readable, parse-error, ...)
- key derivation function (KDF)
- work-factor for the KDF
--work-factor <num>(valid range: 0-2^32-1). KDF may apply its own narrower limits. Default value dependent on KDF.
Usage: ./mysqlrouter_passwd [--delete] [-?|--help] [--kdf=<name>] [--list] [--verify] [-V|--version] [--work-factor=<num>] [filename username] Options: --delete Delete username if it exists. -?, --help Display this help and exit. --kdf <name> Key Derivation Function. One of pbkdf2-sha256, pbkdf2-sha512, sha256-crypt, sha512-crypt. default: sha256-crypt --list List account(s). --verify Verify password against stored hash for username. Exit-code is 0 if password matches, 1 otherwise -V, --version Display version information and exit. --work-factor <num> Work-factor hint for KDF if account is updated.
Uses the "File Authentication Backend" of the HTTP component.