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 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 thehtpasswd
filename (recommended) or relative./
to the workdir (less secure).endpoints
(list - optional): An array to restrict which endpoints are protected with basic authentication. Theendpoints
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):
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.