The API key authentication enables a Role-Based Access Control (RBAC) and a rate-limiting mechanism by reading the Authorization
header of incoming requests. For the desired endpoints, KrakenD rejects requests from users that do not provide a valid key, are trying to access a resource with insufficient permissions for the user’s role, or ara exceeding the defined quota.
The authentication is granular and works per-endpoint, meaning that you can combine public endpoints (no API Key needed) and private endpoints in the same configuration.
The API Key component requires you to declare at least two different blocks of configuration:
extra_config
middleware section.The first block of configuration declares all API Keys with roles recognized by the system. The API keys middleware configuration requires a single keys
attribute with a list of objects declaring each client’s key
and roles
. The configuration is as follows:
{
"version": 3,
"extra_config": {
"auth/api-keys": {
"keys": [
{
"key": "4d2c61e1-34c4-e96c-9456-15bd983c5019",
"roles": ["role1", "role2"],
"@description": "ACME Inc."
},
{
"key": "58427514-be32-0b52-b7c6-d01fada30497",
"roles": ["role1","role3"],
"@description": "Administrators Inc."
}
]
}
}
}
keys
list: A list of objects containing the following attributes:key
string: The secret key used by the client to access the resources.role
list: All the roles this user has. See roles as all the identifying labels that belong to this client.It is also shown in the example a @description
attribute to help you identify who this key belongs to. This attribute is metadata and unneeded by KrakenD, but it easies the administration of keys.
Now that you have all users and roles declared, it’s time to reference them in the endpoints. For all the endpoints needing API Key validation, you need to include the middleware’s namespace (auth/api-keys
) in its extra_config
. Any endpoints not having the namespace are not considered to be API Key protected. The endpoints could look like this:
{
"endpoint": "/admin",
"backend": [
{
"url_pattern": "/__debug/admin",
"host": [
"http://localhost:8080"
]
}
],
"extra_config": {
"auth/api-keys": {
"roles": [
"admin"
],
"client_max_rate": 5
}
}
}
The endpoint configuration accepts the following parameters:
roles
(array): The list of roles that are allowed to access the endpoint. Values must match exactly with their definitions in the keys
section. API Keys not having the right role, or unauthenticated requests, will receive a 401 Unauthorized
.client_max_rate
(integer - optional): Whether if you want to limit the usage of the endpoint to this specific user at a number of requests per second. Exceeding the number of requests per second will throw to the client a 429 Too Many Requests
HTTP status code.Here is a full example of two different API Keys that can access three different endpoints:
{
"version": 3,
"extra_config": {
"auth/api-keys": {
"keys": [
{
"@description": "ACME Inc.",
"key": "4d2c61e1-34c4-e96c-9456-15bd983c5019",
"roles": ["user", "whitelabel"]
},
{
"@description": "Administrators Inc.",
"key": "58427514-be32-0b52-b7c6-d01fada30497",
"roles": ["admin", "user"]
}
]
}
},
"endpoints": [
{
"endpoint": "/public",
"backend": [
{
"url_pattern": "/__debug/public",
"host": [
"http://localhost:8080"
]
}
]
},
{
"endpoint": "/admin",
"backend": [
{
"url_pattern": "/__debug/admin",
"host": [
"http://localhost:8080"
]
}
],
"extra_config": {
"auth/api-keys": {
"roles": [
"admin"
],
"client_max_rate": 5
}
}
},
{
"endpoint": "/user",
"backend": [
{
"url_pattern": "/__debug/user",
"host": [
"http://localhost:8080"
]
}
],
"extra_config": {
"auth/api-keys": {
"roles": [
"user"
]
}
}
}
]
}
The final step is to make requests again KrakenD adding the Authorization: Bearer
header, or using Basic
authentication. The value inside the header represents the API key defined in the configuration.
Bearer
The format of the header is as follows:
Authorization: Bearer YOUR-KEY
For instance, having declared in the configuration a key 4d2c61e1-34c4-e96c-9456-15bd983c5019
that should be capable of seeing /foo
, you should make a call like this:
Basic
authenticationAnother way of authenticating is using Basic
authentication. The key needs to be encoded in base64
:
Authorization: Basic base64(YOUR-KEY:)
Notice that the encoding of the key contains an ending :
(this prevents your client to be asked for a password).
Using the same key in the previous example:
Or just using your client regular basic auth which will encode automatically (again, notice the :
at the end of the key):
In case you forget the colon :
you’ll be prompted for the password (when there isn’t):
The following configuration snippet is fully functional. Run KrakenD with the debug flag (krakend run -d
) to test it locally, as it uses itself as a backend. Explanation below:
{
"version": 3,
"extra_config": {
"auth/api-keys": {
"keys": [
{
"@description": "ACME Inc.",
"key": "4d2c61e1-34c4-e96c-9456-15bd983c5019",
"roles": [
"user",
"whitelabel"
]
},
{
"@description": "Administrators Inc.",
"key": "58427514-be32-0b52-b7c6-d01fada30497",
"roles": [
"admin",
"user"
]
}
]
}
},
"endpoints": [
{
"endpoint": "/public",
"backend": [
{
"url_pattern": "/__debug/public",
"host": [
"http://localhost:8080"
]
}
]
},
{
"endpoint": "/admin",
"backend": [
{
"url_pattern": "/__debug/admin",
"host": [
"http://localhost:8080"
]
}
],
"extra_config": {
"auth/api-keys": {
"roles": [
"admin"
]
}
}
},
{
"endpoint": "/user",
"backend": [
{
"url_pattern": "/__debug/user",
"host": [
"http://localhost:8080"
]
}
],
"extra_config": {
"auth/api-keys": {
"roles": [
"user"
]
}
}
}
]
}
In this example we have enabled two different API users. One with key 4d2c61e1-34c4-e96c-9456-15bd983c5019
(let’s say a customer of ACME Inc.) and another one with the key 58427514-be32-0b52-b7c6-d01fada30497
(an administrator of my company).
Both users share the role users
and they can access all the protected endpoints as this role is included. Nevertheless, the /admin
endpoint is reachable by the administrator only, as the role “admin” is required.
The endpoint /public
is always accessible, with or without the Authorization
header as it does not include the API key middleware configuration.
And now some sample interactions:
As the KrakenD configuration is static and does not change until you restart the process or you do a deployment, you might find inconvenient to onboard new customers with new API keys and you don’t want to be restarting the server every time, the following advice can be handy.
Instead of waiting for a user registration in your system to generate an insert a new API key, create a pool of available API keys. KrakenD has a constant performance, so it doesn’t change if you have 100 keys or 1 million or more.
An easy way to generate API keys could be as follows:
If you want to generate several keys and write part of the configuration file you could use something like:
Then you would use the output above to create a partial file api-keys.json
that would be used on KrakenD with Flexible Configuration.
Finally, your backend should have this list somewhere, and when a new user registers, you assigns one of the free keys to the new user. You can deploy from time to time when you are running out of api keys in the pool or if you want to write the assignation in the configuration, but this is of course not needed.
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.
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