Basic endpoint authentication using .htpasswd

Document updated on May 25, 2020

The Basic Authentication plugin protects the access to selected endpoints using basic username and password credentials. The functionality works at the router level, and when the authentication fails, the backend is never hit.

How does it work

Basic auth functionality is provided by a plugin, meaning that a separate binary needs to be included. To do so, make sure to provide basic-auth.so, and set the configuration as described below.

KrakenD feeds from a regular.htpasswd file that declares all the possible combinations of users and credentials that KrakenD recognizes. You can also declare users inline, directly in the configuration file. These credentials are stored in bcrypt format. There is no special tooling required to administer this file other than having the htpasswd command in the development machine (the command is part of the apache2-utils package in Linux).

When KrakenD starts, it reads the the .htpasswd file if declared in the configuration and loads it in-memory. The credential checking process does not need to open the file, ensuring that the system does not rely on I/O.

Then, in the configuration, you define which endpoints need authentication through a global list. The basic authentication applies only to endpoints defined. The rest are public or use other authentication/authorization mechanisms.

Configuration

Include the basic-auth.so from the plugins folder and add the following configuration in the root level of your krakend.json.

{
    "version": 3,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "extra_config": {
        "plugin/http-server": {
            "name": [ "basic-auth" ],
            "basic-auth": {
                "htpasswd_path": "/path/to/.htpasswd",
                "endpoints": [
                    "/user/{id}",
                    "/checkout"
                    ],
                "users": {
                    "admin": "$2y$05$HpdPmv2Z3h3skMCVaf/CEep/UUBuhZ...",
                    "user2": "$2y$05$HpdPmv2Z3h3skMCVaf/CEep/UUBuhZ..."
            }
        }
    }
}

As this is a plugin, there is a shared part with other plugins, such as the plugin key defining in which folder are the plugins found and with which extension (pattern). The folder is relative to your workdir.

Secondly, as this is router plugin, it uses the namespace plugin/http-server in the global extra_config section, which is common to all router plugins.

Finally, all the plugins that are enabled are declared in the name array. In this case we want to enable the plugin basic-auth and the configuration keys are stored under basic-auth as follows:

• htpasswd_path (string): Absolute Path to the htpasswd filename (recommended) or relative ./ to the workdir (less secure).
• endpoints (list - optional): An array to restrict which endpoints are protected with basic authentication. The endpoints values must match with the declaration of endpoints in your configuration, including any {placeholders} in the path. Use ["*"] or delete this property to protect all endpoints.
• users (map - optional): Additional users to the htpasswd file can be declared directly inside the configuration. The content of both places will be merged (and will overwrite users already defined in the htpasswd file).

User administration

The htpasswd file is loaded only during startup and KrakenD needs to be restarted or redeployed if you want to modify which users can access the resources. The same thing happens with any users declared inside the users array.

KrakenD only works with passwords encrypted with bcrypt. Generate a file using the following command (notice the -B flag for bcrypt):

$htpasswd -Bbc .htpasswd yourUser yourPassword

Or generate the output in stdout:

$htpasswd -nB yourUser
New password:
Re-type new password:
yourUser:$2y$05$s8eiQOQtfvOPB3K4vr212eZyZFdtdnKap6RfEVd479xXtXlfx7Nsq

A string like the one below represents the user and the password hash, this is what is inserted in the .htpasswd file, or directly inside the KrakenD configuration under users separating the username and the hash (split using user:hash):

$myName:$2y$05$c4WoMPo3SXsafkva.HHa6uXQZWr7oboPiC2bT/r7q1BB8I2s0BRqC

To delete users, simple edit the file and remove the desired line.

Deploying

Make sure to deploy KrakenD along with the plugin folder and the .htpasswd file.