Basic Auth

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). 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.

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 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.

Starting in Kong Gateway 3.13, you can authenticate with a cloud Redis provider for your Redis strategy. 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)

Each provider also supports an instance and cluster configuration.

Important: Kong Gateway open source plugins do not support any Redis cloud provider cluster configurations.

To configure cloud authentication with Redis, add the following parameters to your plugin configuration:

config:
  storage: redis
  storage_config:
    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:
  storage: redis
  storage_config:
    redis:
      cluster_nodes:
      - ip: $CLUSTER_ADDRESS
        port: 6379
      username: $CLUSTER_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:
  storage: redis
  storage_config:
    redis:
      host: $INSTANCE_ADDRESS
      username: $INSTANCE_USERNAME
      port: 6379
      cloud_authentication:
        auth_provider: azure
        azure_client_id: $AZURE_CLIENT_ID
        azure_client_secret: $AZURE_CLIENT_SECRET
        azure_tenant_id: $AZURE_TENANT_ID

config:
  storage: redis
  storage_config:
    redis:
      cluster_nodes:
      - ip: $CLUSTER_ADDRESS
        port: 6379
      username: $CLUSTER_USERNAME
      port: 6379
      cloud_authentication:
        auth_provider: azure
        azure_client_id: $AZURE_CLIENT_ID
        azure_client_secret: $AZURE_CLIENT_SECRET
        azure_tenant_id: $AZURE_TENANT_ID

config:
  storage: redis
  storage_config:
    redis:
      host: $INSTANCE_ADDRESS
      port: 6379
      cloud_authentication:
        auth_provider: gcp
        gcp_service_account_json: $GCP_SERVICE_ACCOUNT

config:
  storage: redis
  storage_config:
    redis:
      cluster_nodes:
      - ip: $CLUSTER_ADDRESS
        port: 6379 
      port: 6379
      cloud_authentication:
        auth_provider: gcp
        gcp_service_account_json: $GCP_SERVICE_ACCOUNT