Document updated on Feb 22, 2023
The Basic Authentication functionality protects access to selected endpoints using basic username and password credentials. The functionality works at the router level, and the backend is never hit when the authentication fails.
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. You must store these credentials 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 .htpasswd
file if declared in the configuration and loads it in memory. As a result, the credential-checking process does not need to open the file, ensuring that the system does not rely on I/O.
The basic authentication applies only to the endpoints containing an auth/basic
entry. The rest are public or use other authentication/authorization mechanisms.
When a user fails to provide valid credentials, a 401 Unauthorized
status code is returned.
The namespace you need to enable basic authorization is auth/basic
, and you can place it at the endpoint level (required), the service level (optional), or both.
Include the auth/basic
’s extra_config
in the desired endpoint that needs to check the credentials with the credentials file and/or usernames. If you want to use the same credential sets across multiple endpoints, you can place the namespace at the service level instead (root of the file) and include an empty extra_config
reference ("auth/basic": {}
) which will inherit its settings.
When the endpoint includes a non-empty configuration object, if you have declared settings at the service level, then you are overriding the whole object.
For instance:
{
"version": 3,
"extra_config": {
"auth/basic": {
"@comment": "The following configuration applies to any endpoint with auth/basic{} config",
"htpasswd_path": "/path/to/.htpasswd",
"@comment": "Additional users to the ones in htpasswd:",
"users": {
"admin": "$2y$05$HpdPmv2Z3h3skMCVaf/CEep/UUBuhZ...",
"user2": "$2y$05$HpdPmv2Z3h3skMCVaf/CEep/UUBuhZ..."
}
}
},
"endpoints": [
{
"endpoint": "/user/{id}",
"extra_config": {
"@comment": "The empty inclusion enables basic auth for this endpoint with the config above ",
"auth/basic": {}
}
},
{
"endpoint": "/checkout",
"extra_config": {
"@comment": "Exceptionally an endpoint can override all settings",
"auth/basic": {
"htpasswd_path": "/path/to/.htpasswd_secondary",
}
}
}
]
}
| 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). The key of each entry is the username, and the value the bcrypt.Example: {"admin":"$2y$05$HpdPmv2Z3h3skMCVaf/CEep/UUBuhZ...","user2":"$2y$05$HpdPmv2Z3h3skMCVaf/CEep/UUBuhZ..."} Properties of |
Schema: https://www.krakend.io/schema/v2.2/auth/basic.json
* indicates a required field.
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 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, which is inserted in the .htpasswd
file or directly inside the KrakenD configuration under users
.
$myName:$2y$05$c4WoMPo3SXsafkva.HHa6uXQZWr7oboPiC2bT/r7q1BB8I2s0BRqC
To delete users, edit the file and remove the desired line.
If you used the basic authentication plugin previous to v2.2, then you should switch to the new configuration format for the new core component that offers the following benefits:
The basic auth plugin is considered deprecated, although it’s still supported for backward compatibility.
Below you can find the same configuration for the deprecated plugin and the core component.
DEPRECATED configuration:
{
"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..."
}
}
}
}
}
CURRENT configuration:
{
"version": 3,
"extra_config": {
"auth/basic": {
"@comment": "The following configuration applies to any endpoint with auth/basic config",
"htpasswd_path": "/path/to/.htpasswd",
"users": {
"admin": "$2y$05$HpdPmv2Z3h3skMCVaf/CEep/UUBuhZ...",
"user2": "$2y$05$HpdPmv2Z3h3skMCVaf/CEep/UUBuhZ..."
}
}
},
"endpoints": [
{
"endpoint": "/user/{id}",
"extra_config": {
"@comment": "The simple inclusion of the component enables basic authentication for this endpoint",
"auth/basic": {}
}
},
{
"endpoint": "/checkout",
"extra_config": {
"auth/basic": {
"@comment": "Additionally an endpoint can override any settings",
"htpasswd_path": "/path/to/.htpasswd_secondary",
}
}
}
]
}
As you can see, your configuration in the plugin moves to a new extra_config
section named auth/basic
. And instead of having a list of endpoints, you declare the usage directly in the endpoint. In summary:
plugins
entryextra_config
/ plugin/http-server
/ basic-auth
extra_config
/ auth/basic
endpoints
list disappears in the global configurationendpoint
the extra_config
-> auth/basic
as an empty objectThe 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.
We use cookies to understand how you use our site and to improve your overall experience. By continuing to use our site, you accept our Privacy Policy. More information