News KrakenD CE v2.8 released with improved Lua and OpenTelemetry

You are viewing a previous version of KrakenD Enterprise Edition (v1.3), go to the latest version

Document updated on May 25, 2020

Basic endpoint authentication using .htpasswd

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 krakend-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.

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 krakend-basic-auth.so from the plugins folder and add the following configuration in the root level of your krakend.json.

{
    "version": 2,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "extra_config": {
        "github_com/devopsfaith/krakend/transport/http/server/handler": {
            "name": [ "krakend-basic-auth" ],
            "krakend-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 github_com/devopsfaith/krakend/transport/http/server/handler 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 krakend-basic-auth and the configuration keys are stored under krakend-basic-auth as follows:

  • htpasswd_path: Absolute Path to the htpasswd filename (recommended) or relative ./ to the workdir (less secure).
  • endpoints: An array with all the endpoints protected with basic authentication. The endpoints values must match with the declaration of endpoints in your configuration, including any {placeholders} in the path.
  • users (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):

Generate access file 

$htpasswd -Bbc .htpasswd yourUser yourPassword

Or generate the output in stdout:

Ask for password and create hash 

$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):

Generate access file 

$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.

Scarf

Unresolved issues?

The documentation is only a piece of the help you can get! Whether you are looking for Open Source or Enterprise support, see more support channels that can help you.

See all support channels