Basic Auth

The Basic Authentication plugin enforces username and password authentication for Consumers or principals v3.15+ when making a request to a Gateway Service or Route. Consumers and principals 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 or a principal v3.15+ to work. When you create the Consumer or the principal, you must specify a username and password, for example: Ariel:Password. The credentials 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 either a Consumer or a principal v3.15+ 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). In Kong Gateway 3.13 or later, you can protect against brute force attacks by enabling config.brute_force_protection. This will return an 429 Too Many Requests error after the fourth failed login attempt.

The Basic Auth plugin supports two types of authenticating entities: Consumers and principals v3.15+.

The following table will help you decide which to use based on your use case:

Using multiple authentication plugins

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 or the principal wasn’t already authenticated. For more information, see Using multiple authentication methods.

Common use cases for the Basic Authentication plugin:

The Basic Auth plugin can be susceptible to brute force and dictionary attacks because rate limiting occurs after authentication plugins, leaving a vulnerability to failed login attempts. You can configure config.brute_force_protection on the plugin to prevent this.

This feature protects against brute force attacks by doing the following:

1. When brute force protection is enabled, the plugin tracks failed login attempts by username.
2. For each failed login attempt using a username and password, a counter is incremented with the username as the key in the shared store. The plugin starts returning a 429 Too Many Requests response on the 3rd failed login attempt. The 429 response includes a Retry-After header, which indicates the remaining Time-To-Live (TTL) of the counter for that username.
3. Each additional failed attempt doubles the previous wait time. The wait time is calculated as 2^(number of failed attempts) seconds, with a maximum configurable wait time of 1 hour. There is no cache to clear.

Keep the following limitations in mind when you configure brute force protection:

• Counters are only reset when their TTL is reached. A successful login attempt does not reset the failed attempt counter. The user will still be blocked until the TTL expires.
• There is no way to unlock a user. You can manually delete the counter key from Redis or PostgreSQL.
• If the Redis connection fails, the brute force protection will error out.
• Each backend has different impacts on performance. In-memory has the best performance, PostgreSQL the poorest, and Redis is better than PostgreSQL.

If your plugin uses a Redis datastore, you can authenticate to it with a cloud Redis provider. This allows you to seamlessly rotate credentials without relying on static passwords.

The following providers are supported:

• AWS ElastiCache
• Azure Managed Redis
• Google Cloud Memorystore (with or without Valkey)

config:
  brute_force_protection:
    strategy: redis
    redis:
      host: $INSTANCE_ADDRESS
      username: $INSTANCE_USERNAME
      port: 6379
      cloud_authentication:
        auth_provider: aws
        aws_cache_name: $AWS_CACHE_NAME
        aws_is_serverless: false
        aws_region: $AWS_REGION
        aws_access_key_id: $AWS_ACCESS_KEY_ID
        aws_secret_access_key: $AWS_ACCESS_SECRET_KEY

config:
  brute_force_protection:
    strategy: redis
    redis:
      host: $INSTANCE_ADDRESS
      username: $INSTANCE_USERNAME
      port: 10000
      cloud_authentication:
        auth_provider: azure
        azure_client_id: $AZURE_CLIENT_ID
        azure_client_secret: $AZURE_CLIENT_SECRET
        azure_tenant_id: $AZURE_TENANT_ID

config:
  brute_force_protection:
    strategy: redis
    redis:
      host: $INSTANCE_ADDRESS
      port: 6379
      cloud_authentication:
        auth_provider: gcp
        gcp_service_account_json: $GCP_SERVICE_ACCOUNT