The Basic Authentication plugin enforces username and password authentication for Consumers when making a request to a Gateway Service or Route. Consumers represent a developer or an application consuming the upstream service.
Basic authentication can be used with both HTTP and HTTPS requests and is an effective way to add simple password protection to web applications.
The Basic Authentication plugin requires at least one Consumer to work. When you create the Consumer, you must specify a username and password, for example: Ariel:Password. The Consumer’s password must be base64-encoded when it’s used in the Authentication header. For example, Ariel:Password would become QXJpZWw6UGFzc3dvcmQ=.
Then, you can enable the plugin on a Gateway Service, Route, or globally. When a Consumer makes a request to the associated Gateway Service or Route, the plugin checks for valid credentials in the Proxy-Authorization and Authorization headers (in that order).
You can use the Basic Authentication plugin along with other authentication plugins. This allows clients to use different authentication methods to access a given Gateway Service or Route.
The authentication plugins can be configured to always require authentication or only perform authentication if the Consumer wasn’t already authenticated. For more information, see Using multiple authentication methods.
Common use cases for the Basic Authentication plugin:
|
Use case |
Description |
|---|---|
| Allow or deny requests on a Gateway Service or Route | Configure both the ACL and Basic Authentication plugins to restrict access to a Service or a Route by adding Consumers to allowed or denied lists using arbitrary ACL groups. |
| Authenticate on the upstream service |
Configure the Basic Authentication plugin on a Route and then configure the Consumer credential in the config.add.headers property for the Request Transformer plugin.
|
| Allow clients to choose their authentication method |
Enable the Basic Authentication plugin and any other authentication plugins. Use the config.anonymous property on the plugins to determine if authentication is always performed or only when the Consumer wasn’t already authenticated.
|
| Check credentials per session | When the Session plugin is enabled in conjunction with an authentication plugin, it runs before credential verification. If no session is found, then the authentication plugin runs again and credentials are checked normally. If the credential verification is successful, then the Session plugin creates a new session for usage with subsequent requests. |
| Rate limit unauthenticated and authenticated users differently | You can configure a given Service to allow both authenticated and anonymous access. You might use this configuration to grant access to anonymous users with a low rate limit and grant access to authenticated users with a higher rate limit using the Rate Limiting plugin. |
| Use basic authentication for Kong Manager | If you want users to authenticate before logging in to Kong Manager, you can configure basic authentication for the GUI. |
I updated my Consumer’s username, why doesn’t their password or basic authentication work anymore?
The basic auth password credential is encrypted in the database. Kong Gateway can only get the encrypted value of the password from the database. When you update the username or tag, Kong Gateway overwrites the password with its encrypted value. To fix this, enter the original password when you update the username or tag of the basic auth credential.
How do I delete a Consumer credential?
You can delete a specific credential by sending a DELETE request to /{workspace_id_or_name}/consumers/{consumer_id_or_name}/basic-auth/{credentials_id}.
I’m migrating from Kong Gateway to Konnect and using deck gateway dump, will this also dump my basic auth credentials?
No. The basic auth credentials are stored in the database as hashed values. When you dump the configuration with decK, it will retrieve these hashed values, not the original plain-text passwords. Since there is currently no way to extract the initial plain-text values of the basic auth credentials due to how they are stored, you will need to manually set the passwords for basic auth after dumping the configuration or by directly setting up the password in Konnect.
Why should I use the Basic Authentication plugin instead of other authentication plugins, like Key Authentication?
You should use basic authentication when you need a simple way to authenticate and security isn’t a concern. For example, you could use this plugin to connect internal server networks or as a verification on open data. Use Key Authentication or another authentication plugin if you require additional security.
