News KrakenD CE v2.7 released with better rate-limiting and security options

Enterprise Documentation

Recent changes

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

Basic endpoint authentication using .htpasswd

Document updated on Oct 25, 2022

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


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

    "version": 3,
    "plugin": {
        "folder": "/opt/krakend/plugins/"
    "extra_config": {
        "plugin/http-server": {
            "name": [ "basic-auth" ],
            "basic-auth": {
                "htpasswd_path": "/path/to/.htpasswd",
                "endpoints": [
                "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:

Fields of "plugin/basic-auth"
* required fields
endpoints  *

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.
Examples: ["*"] , ["/user/{id}","/checkout"]
htpasswd_path  *

Absolute Path to the htpasswd filename (recommended) or relative ./ to the workdir (less secure).
Example: "/path/to/.htpasswd"

Additional users to the htpasswd file can be declared directly inside the configuration. The content of both places will be merged (and this list will overwrite users already defined in the htpasswd file).
Example: {"admin":"$2y$05$HpdPmv2Z3h3skMCVaf/CEep/UUBuhZ...","user2":"$2y$05$HpdPmv2Z3h3skMCVaf/CEep/UUBuhZ..."}

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:

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 

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


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


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.